Introduction ("Store" Extension Fucntions) | WS.WebTV API Reference | WebTV Solutions

Print

Before starting to work with the "Store" extension API functions, you must read the following information with important details you need to know (including workflows).

General note

All functions use the currency selected in the "Store" configuration. You can't perform operations using a currency different than the configured one.

Workflows

Current content and subscriptions for a user

- You can get the current content (current Clip or Channel access passes) for an User with the function "list_current_content".
- You can get the list of (current) subscriptions of an User with the function "list_subscriptions".

User credit

- You can get the current User credit with the function "get_credit".
- You can (arbitrarily) add/subtract credit to/from an User with the function "add_subtract_credit".

Product info

When you want to display a product related to a content (Clip, Channel...), use the "get_product" function in order to retrieve the related info. You can also use this function to get the list of general (non-content) Store products (Credits, Global Access Passes, Memberships, Services, Donations...).

Working with the shopping cart and placing/paying an order

Here is an overview of the process and functions involved:
- You can get the cart content any time using the function "get_cart". This function will also return the total amounts.
- You can add/remove products from the cart (providing the product ID) using the function "modify_cart" (this function also allows you to empty the cart).
- Once the User is ready to place an order (and pay) you will use the following functions:
- "place_order": Use this function to place an order from the products in the shopping cart. Once the order is placed, the shopping cart is emptied. If you want to get the current order details after it was placed then you can use the function "get_cart" and it will return the details of the current order instead of the cart.
- "cancel_order": Use this function to cancel the current order (for whatever reason). Note that once an order was placed, it can't be modified. If you or the User needs to modify an order then it must cancelled and start from scratch.
- "get_cart": When an order was placed and has not been paid (is current), this function will return the details for it (instead of the cart which is empty); remember that it will also return the total amounts.
- "add_payment": After placing an order you will normally bill the user. Once you have billed the user you must add the corresponding payment transaction using this function. You can add several payments to an order as long as the sum of payments totals the amount due.
- "process_order": Once the amount due is 0 (you can use the "get_cart" function to verify this) you can process the order with this function. This function will set the current order status as "paid" and will process the items.

In short, the full workflow for placing and paying an order would be:
1. Add products to the cart (modify_cart).
2. Place the order (place_order).
3. Bill the user for the total amount due of the order.
4. Add payment to the order (add_payment).
5. Process the order (process_order).
6. Reload CVR of the User (users > get_cvr).

Optional: What about recurring (automatic) payments for subscriptions? And subscriptions with free trials (WS.WebTV 3.0.2+)?
NOTE: If you don't set recurring payments, the WebTV will ask the User to pay when the renewal date for a subscription is near.
If you plan to implement recurring payments from your application then:
- If you won't use PayPal, then you must first implement the External Payment Processor and configure this payment method in the "Store" extension configuration.
- If you will use PayPal for recurring payments then make sure this payment method is correctly set in the "Store" extension configuration.

Overview of the additional process and functions involved:
- When placing an order, get the IDs of all the products with "type name" equal to "SUBSCRIPTION", "SUBSCRIPTIONTRIAL" or "SUBSCRIPTIONRENEWAL".
- When you bill the User you must create (on your side) a recurring payment profile (agreement/contract) for each subscription. For doing this, you need to know the recurring payment info (amount, currency code, period, frequency...), you can get this info using the function "get_subscription_pre_rp_info" by providing the product ID.
- After you have the recurring payment profiles for each subscription product (and after the order was processed and the subscriptions were created...) then you can use the "get_subscription_pre_rp_info" function again to get the subscription ID for each product and; finally, you can set the recurring payments in the "Store" extension using the function "set_subscription_rp" (by providing the subscription ID and the recurring payments info for each subscription).

In short, the full workflow for placing and paying an order with subscriptions (no free trial) and with recurring payments, would be:
1. Add products to the cart (modify_cart).
2. Place the order (place_order) and get the ID of the subscription products (get_cart).
3. Get the recurring payments info for each of the subscription products (get_subscription_pre_rp_info).
4. Bill the user for the total amount due of the order and create the recurring payment profiles for each subscription product (and save the relevant info for use on next steps...)
5. Add payment to the order (add_payment).
6. Process the order (process_order)
7. Get the recurring payments info again, for the subscription products (get_subscription_pre_rp_info), in order to know the subscription ID for each one.
8. For each subscription, use the subscription ID along with the recurring payments profile info from point 4 to set the recurring payments profiles in the "Store" (set_subscription_rp).
9. Reload CVR of the User (users > get_cvr).

In short, the full workflow for placing and paying an order with subscriptions (with free trial) and with recurring payments, would be:
1. Add the subscription trial product to the cart. This kind of product can only be added alone to the cart. (modify_cart).
2. Place the order (place_order) and get the ID of the subscription product (get_cart).
3. Get the recurring payments info for the subscription product (get_subscription_pre_rp_info).
4. Since it is a trial, there is nothing to bill the user but you need to create the recurring payment profile for the subscription product (and save the relevant info for use on next steps...)
5. Process the order (process_order)
6. Get the recurring payments info again, for the subscription product (get_subscription_pre_rp_info), in order to know the subscription ID.
7. Use the subscription ID along with the recurring payments profile info from point 4 to set the recurring payments profile in the "Store" (set_subscription_rp).
8. Reload CVR of the User (users > get_cvr).