Optional: Set amounts on Subscription Charges

📘

Optional

The step is optional if you setup a product with a default quantity of 1. Typically what you do for a simple sale of 1 pc. License for your Subscription Product.

In Upodi a subscription will contain subscription charges - one for each product available to the customer on this particular subscription. Depending on your setup in your Product Plan you may have to set amounts in order to "put stuff in the basket" for your customer.

👍

Quantity of zero

Usually your Subscription Charges come with a quantity of zero (0). Don't worry. If the customer bought zero pc. of a product it's simply not printed to the invoice.

There are different routes to achieve this next step.

Option #1 You know the Product Plan Charge ID's

One way is to simply store and keep the Product Plan Charge ID's to be used to update the correct Subscription Charges.

curl -X GET \
  'https://api.upodi.io/v3/productplans/query?$expand=ProductPlanCharges,ProductPlanChargePricings' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {Base64EncodedAPIKey' \
  -H 'Content-Type: application/json' \
UpodiService Upodi = new UpodiService("{APIKey}");
var ListOfProductPlans = Upodi.ProductPlans.List(all: true);

You get a response similar to this:

{
    "Items": [
        {
            "ProductPlanCharges": [
                {
                    "FullName": "Product A",
                    "InvoiceText": "Product A",
                    "DefaultAmount": 1,
                    "SKU": "{Stock Keeping Unit}",
                    "ID": "guid"
                    ...
                },
                {
                    "FullName": "Product B",
                    "InvoiceText": "Product B",
                    "DefaultAmount": 0,
                    "SKU": "{Stock Keeping Unit}",
                    "ID": "guid"
                    ...
                }
            ],
            "FullName": "Product Plan A",
            "CurrencyCode": "DKK",
            "ActiveCurrencies": "DKK",
            "ID": "guid",
            ...
        }
      ]
}

Save the ID's from the Product Plan Charges to set amounts.

Option #2 You know the SKU of the Product Plan Charge.

curl -X GET \
  'https://api.upodi.io/v3/productplans/query?$expand=ProductPlanCharges&$filter=ProductPlanCharges/all%28o:%20o/SKU%20eq%20%27{SKU HERE}%27%29' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {Base64EncodedAPIKey}' \
  -H 'Content-Type: application/json' \

Response:

{
    "Items": [
        {
            "ProductPlanCharges": [
                {
                    "FullName": "Product A",
                    "InvoiceText": "Product A",
                    "DefaultAmount": 0,
                    "SKU": "{Stock Keeping Unit}",
                    "ID": "guid",
                    ...
                }
            ],
            "FullName": "Product Plan A",
            "CurrencyCode": "DKK",
            "ActiveCurrencies": "DKK",
            "ID": "guid",
            ...
        }
      ]
}

Save the ID of the Product Plan Charge. This is the product you want to set the quantity on.

Set Quantity on Active Subscription Charges

In Upodi we create new Subscription Charges along the way, when the old ones have been charged. Therefore, what you need is to update amount on the active Subscription Charges. You can make use of the Upodi endpoint /subscriptioncharges/{referenceId}/setamountbyreferenceid which will always automatically update the quantity on the active Subscription Charge.

With the Product Plan Charge ID locate the ReferenceID on the desired SubscriptionCharge

curl -X GET \
  'https://api.upodi.io/v3/subscriptioncharges/query?$filter=SubscriptionID%20eq%20guid%27{SubscriptionID}%27' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {Base64EncodedAPIKey}' \
  -H 'Content-Type: application/json' \
UpodiService Upodi = new UpodiService("{APIKey}");
var listOfCharges = Upodi.Subscriptions.ListCharges("{SubscriptionID}", true);

This returns a response with all Subscription Charges on the Subscription:

{
    "Items": [
        {
            "Amount": 0,
            "NextChargeDate": "2019-06-06T22:01:00Z",
            "SubscriptionID": "0987cd34-bfc6-4d50-b384-1650a4fa53ab",
            "ProductPlanChargeID": "guid",
            "StateCode": 1,
            "Status": 1,
            "ReferenceID": "ccfa2824-b237-4841-8321-e2aeddrty555",
            "ID": "guid",
            ...
        },
        {
            "Amount": 0,
            "NextChargeDate": "2019-06-06T22:01:00Z",
            "SubscriptionID": "0987cd34-bfc6-4d50-b384-1650a4fa53ab",
            "ProductPlanChargeID": "guid",
            "StateCode": 1,
            "Status": 7,
            "ReferenceID": "ccfa2824-b237-4841-8321-e2aed675rtr",
            "ID": "guid",
            ...
        }
    ]
}

Save the ReferenceID for the next step. This referenceID will always refer to that particular Product (ProductPlanCharge) on this particular Subscription.

Set Amount by ReferenceID

Make a PUT to the endpoint /subscriptioncharges/{referenceId}/setamountbyreferenceid

curl -X PUT \
  https://api.upodi.io/v3/subscriptioncharges/{ReferenceID}/setamountbyreferenceid \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {Base64EncodedAPIKey}' \
  -H 'Content-Type: application/json' \
  -d '{
    "quantity": 5
}'
UpodiService Upodi = new UpodiService("{APIKey}");
Upodi.SubscriptionCharges.SetAmount("{SubscriptionChargeID}", 5);