Shopping Service

The shopping service is responsible for managing the purchase process, this includes promo codes and integration with payment gateways.

Summary: Get the details of the specified promo code
Authentication: X-Auth Admin
                      GET /services/shopping/v1/discounts/[discount_id]
                    

Description

Use this API to get the details of the specified promo code. This API is only accessible to users who have the admin role.

Response Parameters

Parameter Type Description
id number The unique promo code ID.
enabled bool Determines if the promo code is enabled or disabled.
name string Name of the promo code.
code string The promo code that users enter to receive a discount.
discount_percentage string The percentage discount that will be applied.
limit_number number The maximum number of times this promo code can be used.
redeemed_number number The number of times this promo code has been used.
start_date string The ISO 8601 time and date the promo code can be used from.
expiry_date string The ISO 8601 time and date the promo code can no longer be used. Null means there is no expiry date.
items array Array of slugs that the discount applies to. Applies to all if this is empty.
ownership string The type of purchase this applies to. Either “rent”, “buy”, or null if it’s not restricted.

Examples

Show the Details of Promo Code 19

curl -i 'https://store.shift72.com/services/shopping/v1/discounts/19' \
  -H 'x-auth-token: 1a1f4363bac4df5ba34758945fae8d0d'

Response: Success

HttpStatus: 200
{  
  "id":19,
  "enabled":true,
  "name":"Test",
  "code":"ILU55KBV56BL",
  "discount_percentage":"20.0",
  "limit_number":100,
  "redeemed_number":0,
  "start_date":"2015-06-07T20:39:45.000Z",
  "expiry_date":"2015-06-11T20:39:59.493Z",
  "ownership": "buy",
  "items": [
    "/film/97",
    "/film/92",
    "/film/78",
    "/film/71"
  ]
}

Response: Unauthorized

HttpStatus: 401
Summary: Create a new promo code
Authentication: X-Auth Admin
                      POST /services/shopping/v1/discounts/
                    

Description

Use this API if you are an administrator and want to create a new promo code. This API is only accessible to users who have the admin role.

To enable a created promo code see Promo Codes (Update)

Request Parameters

Parameter Type Description
name string Required. Name of the promo code.
code string Required. The promo code that users enter to receive a discount.
discount_percentage string Required. The percentage discount that will be applied.
limit_number number Optional. The maximum number of times this promo code can be used.
can_be_reused bool Optional. Whether the code can be reused by the same user.
start_date string Required. The ISO 8601 time and date the promo code can be used from.
expiry_date string Optional. The ISO 8601 time and date the promo code can no longer be used. Null means there is no expiry date.
items array Array of slugs that the discount applies to. Leave this empty if it applies to all.
ownership string The type of purchase this applies to. Either “rent”, “buy”, or null if it’s not restricted.

Response Parameters

Returns Promo Code.

Examples

Create a New Promo Code

curl -i 'https://store.shift72.com/services/shopping/v1/discounts/' \
  -X POST \
  -H 'x-auth-token: 1a1f4363bac4df5ba34758945fae8d0d' \
  -H 'content-type: application/json;charset=UTF-8' \
  --data-binary '{  
    "discount":{  
      "code":"HALLOWEEN",
      "start_date":"2015-10-30T00:00:00+12:00",
      "name":"Halloween",
      "discount_percentage":20,
      "ownership": null,
      "items": []
    }
  }'

Response: Success

HttpStatus: 200
{  
  "id":20,
  "client_id":2,
  "name":"Halloween",
  "code":"HALLOWEEN",
  "discount_percentage":"20.0",
  "limit_number":null,
  "redeemed_number":0,
  "start_date":"2015-10-29T12:00:00.000Z",
  "expiry_date":null,
  "created_at":"2015-06-07T21:03:47.782Z",
  "updated_at":"2015-06-07T21:03:47.782Z",
  "enabled":false,
  "ownership": null,
  "items": []
}

Response: Promo Code Already Used

HttpStatus: 422
{  
  "error":{  
    "code":[  
      "Code must be unique"
    ]
  }
}

Response: Unauthorized

HttpStatus: 401
Summary: Delete a promo code
Authentication: X-Auth Admin
                      DELETE /services/shopping/v1/discounts/[discount_id]
                    

Description

Use this API if you are an administrator and want to delete a specific promo code. The promo code cannot be deleted once a user has redeemed a code, i.e. redeemed_number is no longer zero. This API is only accessible to users who have the admin role.

Response Parameters

Parameter Type Description
success bool Deprecated. This is no longer used.
error string A message that provides more information about the error.

Examples

Delete Promo Code 22

curl -i 'https://store.shift72.com/services/shopping/v1/discounts/22' \
  -X DELETE \
  -H 'x-auth-token: 1a1f4363bac4df5ba34758945fae8d0d'

Response: Success

HttpStatus: 200
{  
  "success":true
}

Response: Error

HttpStatus: 422
{  
  "error":"Can't delete, redeemed number is not 0"
}

Response: Unauthorized

HttpStatus: 401
Summary: Search for promo codes
Authentication: X-Auth Admin
                      GET /services/shopping/v1/discounts/search?filter=[filter]&page=[pg]&per_page=[num]&query=[search_string]
                    

Description

Use this API if you are an administrator and want to search the list of promo codes. This searches across the name and code fields. This API is only accessible to users who have the admin role.

Query String Request Parameters

Parameter Description
page The search page number.
per_page The number of items to return per page. All results are returned if this is not passed.
query The string to search on.
filter Filter on specific criteria. Can be one of “live”, “expired”, or “disabled. Leave this field out to remove the filter.

Pagination Header Response Parameters

Pagination information is returned via the header Pagination

Parameter Type Description
page_size number The number of items per page.
first_page number The number of the first page.
next_page number The number of the next page.
prev_page number The number of the previous page.
last_page number The number of the last page.
total_count number The total number of items found in the search.
pages_count number The total number of pages.

Response Parameters

Returns Promo Code.

Examples

Search for Matches on “test”

curl -i 'https://store.shift72.com/services/shopping/v1/discounts/search?page=&per_page=20&query=test' \
  -H 'x-auth-token: 1a1f4363bac4df5ba34758945fae8d0d'

Response: Success

HttpStatus: 200
[  
  {  
    "id":19,
    "enabled":true,
    "name":"Test",
    "code":"ILU55KBV56BL",
    "discount_percentage":"20.0",
    "limit_number":null,
    "redeemed_number":0,
    "start_date":"2015-06-07T20:39:45.000Z",
    "expiry_date":"2015-06-11T20:39:59.493Z",
    "ownership": null,
    "items": []
  },
  {  
    "id":8,
    "enabled":true,
    "name":"test",
    "code":"TEST11",
    "discount_percentage":"11.0",
    "limit_number":null,
    "redeemed_number":1,
    "start_date":"2015-05-18T01:34:22.000Z",
    "expiry_date":null,
    "ownership": null,
    "items": []
  }
]

Response: Unauthorized

HttpStatus: 401
Summary: Update a promo code
Authentication: X-Auth Admin
                      PUT /services/shopping/v1/discounts/[discount_id]
                    

Description

Use this API if you are an administrator and want to update or enable/disable an existing promo code. The discount percentage cannot be changed once a user has redeemed a code, i.e. redeemed_number is no longer zero. This API is only accessible to users who have the admin role.

Request Parameters

The same as the Promo Code (Create) data. To enable a promo code use the parameter below.

Parameter Type Description
enabled boolean Optional. Determines if the promo code is enabled or disabled.

Response Parameters

Returns Promo Code.

Examples

Update Promo Code 19

curl -i 'https://store.shift72.com/services/shopping/v1/discounts/19' \
  -X PUT \
  -H 'x-auth-token: 1a1f4363bac4df5ba34758945fae8d0d' \
  -H 'content-type: application/json;charset=UTF-8' \
  --data-binary '{  
    "discount":{  
      "enabled":true,
      "name":"Test",
      "code":"ILU55KBV56BL",
      "discount_percentage":25,
      "limit_number":null,
      "start_date":"2015-06-07T20:39:45.000Z",
      "expiry_date":"2015-06-11T20:39:59.493Z",
      "ownership": null,
      "items": []
    }
  }'

Response: Success

HttpStatus: 200
{  
  "id":19,
  "enabled":true,
  "name":"Test",
  "code":"ILU55KBV56BL",
  "discount_percentage":"25.0",
  "limit_number":null,
  "redeemed_number":0,
  "start_date":"2015-06-07T20:39:45.000Z",
  "expiry_date":"2015-06-11T20:39:59.493Z",
  "updated_at":"2015-06-07T21:32:18.745Z",
  "ownership": null,
  "items": []
}

Response: Unauthorized

HttpStatus: 401
Summary: Deletes the given subscription for the current user
Authentication: X-Auth
                      DELETE /services/shopping/v1/subscriptions/[subscription_id]
                    

Description

Use this API to delete (cancel) the given subscription for the current user.

Response Parameters

Parameter Type Descriptions
error string A message that provides more information about the error.

Examples

curl -i 'https://studio.shift72.com/services/shopping/v1/subscriptions/240' \
  -H 'x-auth-token: 1a1f4363bac4df5ba34758945fae8d0d'

Response: Success

HttpStatus: 204

Response: Subscription Not Found

HttpStatus: 404
{
  "error":"Specified subscription does not exist",
  "code":"subscription_not_found"
}

Response: Subscription Already Cancelled

HttpStatus: 422
{
  "error":"Specified subscription is already cancelled",
  "code":"subscription_already_cancelled"
}
Summary: Deletes the given subscription for the given user as an admin
Authentication: X-Auth Admin
                      DELETE /services/shopping/v1/subscriptions/[user_id]/subscriptions/[subscription_id]
                    

Description

Use this API to delete (cancel) the given subscription for the given user. This API is only accessible to users who have the admin role.

Response Parameters

Parameter Type Descriptions
error string A message that provides more information about the error.

Examples

curl -i 'https://studio.shift72.com/services/shopping/v1/subscriptions/3280/subscriptions/240' \
  -H 'x-auth-token: 1a1f4363bac4df5ba34758945fae8d0d'

Response: Success

HttpStatus: 204

Response: Unauthorized

HttpStatus: 401

Response: Subscription Not Found

HttpStatus: 404
{
  "error":"Specified subscription does not exist",
  "code":"subscription_not_found"
}

Response: Subscription Already Cancelled

HttpStatus: 422
{
  "error":"Specified subscription is already cancelled",
  "code":"subscription_already_cancelled"
}
Summary: Get the details of the current user's subscriptions
Authentication: X-Auth
                      GET /services/shopping/v1/subscriptions
                    

Description

Use this API to get an array of the current user’s subscription details.

Response Parameters

Parameter Type Descriptions
id number The unique subscription ID.
status string The subscription status (trailing/active/past_due/cancelled/unpaid).
expires_at string The subscription ISO 8601 expiry date.
name string The subscription provider name.
card_id number The unique user card provider ID.

Examples

curl -i 'https://studio.shift72.com/services/shopping/v1/subscriptions' \
  -H 'x-auth-token: 1a1f4363bac4df5ba34758945fae8d0d'

Response: Success

HttpStatus: 200
[
  {
    "id":237,
    "status":"trialing",
    "expires_at":"2019-03-06T20:23:47.000Z",
    "name":"Standard",
    "card_id":206
  }, {
    "id":238,
    "status":"trialing",
    "expires_at":"2019-02-28T20:27:44.000Z",
    "name":"Premium",
    "card_id":207
  }
]

Response: Unauthorized

HttpStatus: 401
Summary: Get the details of a user's subscriptions as an admin
Authentication: X-Auth Admin
                      GET /services/shopping/v1/subscriptions/user/[user_id]/subscriptions
                    

Description

Use this API to get an array of the given user’s subscription details. This API is only accessible to users who have the admin role.

Response Parameters

The same as the Subscriptions GET data.

Examples

curl -i 'https://studio.shift72.com/services/shopping/v1/subscriptions/user/3280/subscriptions' \
  -H 'x-auth-token: 1a1f4363bac4df5ba34758945fae8d0d'

Response: Success

HttpStatus: 200
[
  {
    "id":237,
    "status":"trialing",
    "expires_at":"2019-03-06T20:23:47.000Z",
    "name":"Standard",
    "card_id":206
  }, {
    "id":238,
    "status":"trialing",
    "expires_at":"2019-02-28T20:27:44.000Z",
    "name":"Premium",
    "card_id":207
  }
]

Response: Unauthorized

HttpStatus: 401
Summary: Create a tax configuration
Authentication: X-Auth Admin
                      POST /services/shopping/v1/tax_configurations
                    

Description

Use this API to create a new tax configuration. This API is only accessible to users who have the admin role.

Request Parameters

Parameter Type Description
country_code string ISO 3166-1 two-letter country code.
tax_number string Tax reference number.
tax_percentage number Tax percentage that applies to this configuration.
tax_type string The type of tax e.g “VAT”, “GST”.

Response Parameters

Parameter Type Description
id number The unique tax configuration ID.
country_code string ISO 3166-1 two-letter country code.
tax_number string Tax reference number.
tax_percentage number Tax percentage that applies to this configuration.
tax_type string The type of tax e.g. “VAT”, “GST”.

Examples

Create a Tax Configuration for New Zealand

curl -i 'https://store.shift72.com/services/shopping/v1/tax_configurations' \
  -X POST \
  -H 'x-auth-token: 1a1f4363bac4df5ba34758945fae8d0d' \
  -H 'content-type: application/json;charset=UTF-8' \
  --data-binary '{
    "country_code":"nz",
    "tax_number":"111-111-111",
    "tax_percentage":15,
    "tax_type":"GST"
  }'

Response: Success

HttpStatus: 200
{
  "id":99,
  "country_code":"nz",
  "tax_number":"111-111-111",
  "tax_percentage":15,
  "tax_type":"GST"
}

Response: Tax Configuration with Given Country Code Already Exists

HttpStatus: 409
{
  "error":"a tax configuration already exists for the given country code.",
  "code":"tax_configuration_already_exists"
}

Response: Country Code Parameter Missing

HttpStatus: 422
{
  "error":"country_code is required.",
  "code":"country_code_missing"
}

Response: Tax Type Parameter Missing

HttpStatus: 422
{
  "error":"tax_type is required.",
  "code":"tax_type_missing"
}

Response: Tax Percentage Parameter Missing

HttpStatus: 422
{
  "error":"tax_percentage is required.",
  "code":"tax_percentage_missing"
}

Response: Tax Number Parameter Missing

HttpStatus: 422
{
  "error":"tax_number is required.",
  "code":"tax_number_missing"
}

Response: Tax Configuration Failed to Save

HttpStatus: 422
{
  "error":"database error",
  "code":"tax_configuration_save_failed"
}

Response: Unauthorized

HttpStatus: 401
Summary: Delete a tax configuration
Authentication: X-Auth Admin
                      DELETE /services/shopping/v1/tax_configurations/[configuration_id]
                    

Description

Use this API to delete the specified tax configuration. This API is only accessible to users who have the admin role.

Examples

Delete Tax Configuration 99

curl -i 'https://store.shift72.com/services/shopping/v1/tax_configurations/99' \
  -X DELETE \
  -H 'x-auth-token: 1a1f4363bac4df5ba34758945fae8d0d'

Response: Success

HttpStatus: 204
{}

Response: Tax Configuration Not Found

HttpStatus: 404
{
  "error":"tax configuration not found",
  "code":"tax_configuration_not_found"
}

Response: Unauthorized

HttpStatus: 401
Summary: Get the details of the specified tax configuration by ID
Authentication: X-Auth Admin
                      GET /services/shopping/v1/tax_configurations/[configuration_id]
                    

Description

Use this API to get the details of the specified tax configuration. This API is only accessible to users who have the admin role.

Response Parameters

Returns Tax Configurations

Examples

Show the Details of Tax Configuration 99

curl -i 'https://store.shift72.com/services/shopping/v1/tax_configurations/99' \
  -H 'x-auth-token : 1a1f4363bac4df5ba34758945fae8d0d'

Response: Success

HttpStatus: 200
{
  "id":99,
  "country_code":"nz",
  "tax_number":"111-111-111",
  "tax_percentage":15,
  "tax_type":"GST"
}

Response: Tax Configuration Not Found

HttpStatus: 404
{
  "error":"tax configuration not found",
  "code":"tax_configuration_not_found"
}

Response: Unauthorized

HttpStatus: 401
Summary: Get the details of all tax configurations for the current client
Authentication: X-Auth Admin
                      GET /services/shopping/v1/tax_configurations
                    

Description

Use this API to get an array of tax configuration details for the current client. This API is only accessible to users who have the admin role.

Response Parameters

Returns Tax Configurations

Examples

Show the Tax Configuration Details for Current Client

curl -i 'https://store.shift72.com/services/shopping/v1/tax_configurations' \
  -H 'x-auth-token : 1a1f4363bac4df5ba34758945fae8d0d'

Response: Success

HttpStatus: 200
[
  {
    "id":99,
    "country_code":"nz",
    "tax_number":"111-111-111",
    "tax_percentage":15,
    "tax_type":"GST"
  }, {
    "id":100,
    "country_code":"gb",
    "tax_number":"222-222-222",
    "tax_percentage":20,
    "tax_type":"VAT"
  }
]

Response: Unauthorized

HttpStatus: 401
Summary: Update a tax configuration
Authentication: X-Auth Admin
                      PUT /services/shopping/v1/tax_configurations/[configuration_id]
                    

Description

Use this API to update the details of the specified tax configuration. This API is only accessible to users who have the admin role.

Request Parameters

Parameter Type Description
tax_number string Tax reference number.
tax_percentage number Tax percentage that applies to this configuration.
tax_type string The type of tax e.g “VAT”, “GST”.

Response Parameters

Returns Tax Configurations

Examples

Update Tax Configuration 99

curl -i 'https://store.shift72.com/services/shopping/v1/tax_configurations/99' \
  -X PUT \
  -H 'x-auth-token: 1a1f4363bac4df5ba34758945fae8d0d' \
  -H 'content-type: application/json;charset=UTF-8' \
  --data-binary '{
    "tax_number":"111-111-111",
    "tax_percentage":15,
    "tax_type":"GST"
  }'

Response: Success

HttpStatus: 200
{
  "id":99,
  "country_code":"nz",
  "tax_number":"111-111-111",
  "tax_percentage":15,
  "tax_type":"GST"
}

Response: Tax Configuration Not Found

HttpStatus: 404
{
  "error":"tax configuration not found",
  "code":"tax_configuration_not_found"
}

Response: Tax Type Parameter Missing

HttpStatus: 422
{
  "error":"tax_type is required.",
  "code":"tax_type_missing"
}

Response: Tax Percentage Parameter Missing

HttpStatus: 422
{
  "error":"tax_percentage is required.",
  "code":"tax_percentage_missing"
}

Response: Tax Number Parameter Missing

HttpStatus: 422
{
  "error":"tax_number is required.",
  "code":"tax_number_missing"
}

Response: Tax Configuration Failed to Update

HttpStatus: 422
{
  "error":"database error",
  "code":"tax_configuration_update_failed"
}

Response: Unauthorized

HttpStatus: 401
Summary: Get a user's order history
Authentication: X-Auth Admin
                      GET /services/shopping/v1/order_history/user/[user_id]
                    

Description

Use this API to get the order history of the specified user. This API is only accessible to users who have the admin role.

Response Parameters

Parameter Type Description
id number The unique order ID.
client_id number Deprecated. This is no longer used.
account_id number The user’s unique ID.
item string The slug of the film or TV show and season.
discount_id number The unique discount ID.
ownership string The ownership type of the item, i.e. “buy” or “rent”.
quality string This will either be “hd” or “sd”.
total_price string The amount that was paid during the transaction.
created_at string The ISO 8601 time and date the purchase was made.
updated_at string Deprecated. This is no longer used.
currency string ISO 4217 currency code.
country_code string ISO 3166-1 two-letter country code.
ip_address string The IP address of the user at the time of purchase.
item_price string The original price of the item, before any discount is applied, at the time of the purchase.
total_price_string string The total_price formatted to include the currency symbol.
country_name string The full name of the country_code.

Examples

Get the Order History for User 5769

curl -i 'https://store.shift72.com/services/shopping/v1/order_history/user/5769' \
  -H 'x-auth-token: 1a1f4363bac4df5ba34758945fae8d0d'

Response: Success

HttpStatus: 200
[  
  {  
    "id":3198,
    "client_id":2,
    "account_id":5769,
    "item":"/film/77",
    "discount_id":15,
    "ownership":"rent",
    "quality":"hd",
    "total_price":"3.24",
    "created_at":"2015-06-05T02:19:55.577Z",
    "updated_at":"2015-06-05T02:19:55.577Z",
    "currency":"NZD",
    "country_code":"nz",
    "ip_address":"203.94.55.240",
    "item_price":"6.49",
    "total_price_string":"$3.24 NZD",
    "country_name":"New Zealand"
  },
  {  
    "id":3197,
    "client_id":2,
    "account_id":5769,
    "item":"/film/75",
    "discount_id":null,
    "ownership":"rent",
    "quality":"hd",
    "total_price":"3.49",
    "created_at":"2015-06-05T02:19:02.704Z",
    "updated_at":"2015-06-05T02:19:02.704Z",
    "currency":"NZD",
    "country_code":"nz",
    "ip_address":"203.94.55.240",
    "item_price":"3.49",
    "total_price_string":"$3.49 NZD",
    "country_name":"New Zealand"
  }
]

Response: Unauthorized

HttpStatus: 401
Summary: Add items to a user's library and order history
Authentication: X-Auth System
                      POST /services/shopping/v1/order_history
                    

Description

Create items in the order history and library of a specified user. This API will look up users by external_id and email_address (in order of priority), and, if a matching user isn’t found, will create a new user.

This API is only accessible with an API key.

Request Parameters

Parameter Type Required Description
user[name] string yes The user’s name, will be used if this is a new user
user[email] string yes The user’s email address, will be used to find or create a new user
user[external_id] string no This is a unique identifier that can be used to find an existing user, external id will be checked first before checking if the email address exists.
user[send_invite] bool no Whether to send an invitation email to the provided email address if the user is new to the platform. Defaults to false
order[payment_gateway_token] string no Allows recording an order reference
order[country_code] string yes The country to allocate the purchases. ISO 3166-1 two-letter country code.
order[currency] string no The currency of the purchases, if not specified the currency of the country will be used
order[send_order_confirmation] bool no Whether to send a receipt for the order. Defaults to false
items[item] string yes The slug of the item being purchased.
items[ownership] string yes The ownership of the item ‘rent’ or ‘buy’
items[quality] string yes The quality of the item ‘sd’ or ‘hd’
items[price] number no The price of the item, if no price is specified, the item’s price will be used or 0 if can not be found.
items[expires_at] datetime no Only relevant for Plans. Expiry date of the user’s plan.
items[discount_code] string no The discount code for the item. May be used in conjunction with discount amount but is not required for discounts to be applied. Will be added to the order record for use in reporting.
items[discount_amount] number no The amount the item is to be discounted by, in the same currency denomination as the price, e.g. 0.99. Can be different for each item.

Examples

Post Orders for User Jane Doe

curl -X POST 'http://store.shift72.com/services/shopping/v1/order_history' \
  -H 'x-auth-token: 111be3e60a6a236c875a014e30013748' \
  -H 'content-type: application/json;charset=UTF-8' \
  --data-binary '{
    "user": {
      "name": "Jane Doe",
      "email": "jane.doe@email.com",
      "send_invite": true
    },
    "order": {
      "payment_gateway_token": "PAYMENT_GATEWAY_TOKEN_NNN",
      "country_code": "nz",
      "currency": "USD",
      "send_order_confirmation": true
      
    },
    "items": [
      {
        "item": "/film/124",
        "ownership": "rent",
        "quality": "hd",
        "price": 7.99,
        "discount_code": "PROMO",
        "discount_amount": 4.99,
      },
      {
        "item": "/plan/1",
        "expires_at": "2026-07-31T00:00:00.000Z"
        "price": 27.99
      }
    ]
  }'

Response: Success

HttpStatus: 200

{
  "user": {
    "id": 5917,
    "email": "jane.doe@email.com"
  },
  "items": [
    {
      "item": "/film/124",
      "order_id": 123456,
      "discount_id": null,
      "ownership": "rent",
      "quality": "hd",
      "total_price": "3.00",
      "currency": "USD",
      "country_code": "nz",
      "ip_address": null,
      "item_price": "7.99",
      "pricing_region_id": null,
      "wallet_amount": null,
      "card_amount": "3.00",
      "discount_code": "PROMO",
      "discount_amount": "4.99",
      "tax_percentage": "0.0",
      "item_price_excluding_tax": "7.99",
      "item_price_tax_amount": "0.0",
      "total_price_excluding_tax": "3.00",
      "total_price_tax_amount": "0.0",
      "pricing_region_name": null,
      "total_price_string": "$3.00 USD",
      "country_name": "New Zealand"
    },  
    {
      "item": "/plan/1",
      "order_id": 123457,
      "discount_id": null,
      "expires_at":"2026-07-31T00:00:00.000Z"
      "total_price": "27.99",
      "currency": "USD",
      "country_code": "nz",
      "ip_address": null,
      "item_price": "27.99",
      "pricing_region_id": null,
      "wallet_amount": null,
      "card_amount": "27.99",
      "discount_code": null,
      "tax_percentage": "0.0",
      "item_price_excluding_tax": "27.99",
      "item_price_tax_amount": "0.0",
      "total_price_excluding_tax": "27.99",
      "total_price_tax_amount": "0.0",
      "pricing_region_name": null,
      "total_price_string": "$27.99 USD",
      "country_name": "New Zealand"
    }
  ]
}

Response: Item not found

HttpStatus: 200

{
  "user": {
    "id": 5917,
    "email": "jane.doe@email.com"
  },
  "items": [
    {
      "item": "/film/1000000",
      "ownership": "rent",
      "quality": "hd",
      "price": 7.99,
      "discount_code": "PROMO",
      "discount_amount": 4.99,
      "error": "Invalid request, item not found"
    },
    {
      "item": "/plan/1",
      "expires_at": "2026-07-31T00:00:00.000Z"
      "price": 27.99,
      "error": "Invalid request, item not found"
    }
  ]
}

Response: Unsupported item type

HttpStatus: 200
{
  "user": {
    "id": 5917,
    "email": "jane.doe@email.com"
  },
  "items": [
    {
      "item": "/tv/100/season/200/episode/300",
      "ownership": "buy",
      "quality": "sd",
      "price": 1.99,
      "error": "Invalid request, item not supported"
    }
  ]
}

Response: Required keys missing

HttpStatus: 422

{
    "error": "Invalid request, missing keys: user, order",
    "code": "missing_params"
}

Response: Incorrect value provided

HttpStatus: 422

{
    "error": "Invalid request, invalid data: 1080p",
    "code": "missing_params"
}

Response: Generic/unknown error

HttpStatus: 422

{
    "error": "Invalid request",
    "code": "missing_params"
}

Response: Unauthorized

HttpStatus: 401
Summary: Cancel an existing shopping session
Authentication: X-Auth
                  DELETE /services/shopping/v1/item/[session]/cancel
                

Description

Use this API to cancel a shopping session that was created earlier. This is optional as unused shopping sessions will be deleted after a period, which is currently set to 20 minutes. Canceling a session has the advantage that an unused promo code will be made available again immediately.

Response Parameters

Parameter Type Description
status string Additional information about the status.

Examples

Cancel a Shopping Session

curl -i 'https://store.shift72.com/services/shopping/v1/item/525663e1fba4eb2ff6147895406140e3/cancel' \
  -X DELETE \
  -H 'x-auth-token: b806f604103c2873798159b27ae253f5'

Response: Success

HttpStatus: 200
{
  "status":"cancelled"
}

Response: Invalid Shopping Session

HttpStatus: 403
{  
  "error":"Shopping session not found for provided shopping session token"
}

Response: Unauthorized

HttpStatus: 401
Summary: Request shopping configuration settings
Authentication: None
                  GET /services/shopping/configuration
                

Description

Use this API to get the configuration settings for the Shopping service.

Response Parameters

Parameter Type Description
stripe_pk string The Stripe publishable key.
platform_type string The type of site the user is operating. Can be tvod, svod or avod.

Examples

Shopping Configuration Request

curl -i 'https://store.shift72.com/services/shopping/configuration'

Response: Success

HttpStatus: 200
{  
  "stripe_pk":"pk_test_TPgHyL7vH0rgp1Sr9LFEI3E2"
}
Summary: Create a shopping session which is the start of the purchase process
Authentication: X-Auth
                  POST /services/shopping/v1/item/create
                

Description

Use this API to create a shopping session. This is the first step in making a purchase. The shopping_session_token that is returned is required in other API calls, such as applying a discount or completing the purchase.

Request Parameters

Parameter Type Description
item string Required. The slug of the item to be purchased.
ownership string Required. Whether the purchase is “buy” or “rent”.
quality string Required. Whether the purchase is “hd” or “sd”. Use “hd” unless explicitly for sd content.

Response Parameters

Parameter Type Description
shopping_session_token string The unique ID of the shopping session.
cc_on_file bool Whether the credit card is stored on file. This will always be false.
item string The slug of the item to be purchased.
item_price string The original price of the item, before any discount is applied.
ownership string The ownership type that was requested, i.e. “buy” or “rent”.
quality string The quality. This will either be “hd” or “sd”.
discount_amount string The discount amount that will be applied to this purchase.
total_price string The amount that will be charged to the customer in this transaction.
currency string ISO 4217 currency code.
freebie bool Set to true if the purchase amount is zero.

Examples

Create a Shopping Session for Buying Film 73

curl -i 'https://store.shift72.com/services/shopping/v1/item/create' \
  -H 'x-auth-token: 97d41cf20d38457ab81651db5521f74f' \
  -H 'content-type: application/json;charset=UTF-8' \
  --data-binary '{  
    "shopping_session":{  
      "item":"/film/73",
      "ownership":"buy",
      "quality":"hd"
    }
  }'

Response: Success

HttpStatus: 200
{  
  "shopping_session_token":"28c35f1f1c7d83c77ce45d5c87c9cafb",
  "cc_on_file":false,
  "item":"/film/73",
  "item_price":"$12.99 NZD",
  "ownership":"buy",
  "quality":"hd",
  "discount_amount":"$0.00 NZD",
  "total_price":"$12.99 NZD",
  "currency":"NZD",
  "freebie":false
}

Response: Invalid Request

HttpStatus: 422
{  
  "error":"Invalid request, one or more required params is missing"
}

Response: Geo Blocked

HttpStatus: 403
{  
  "error":"country_denied"
}

Response: Unauthorized

HttpStatus: 401
Summary: Apply a discount to a shopping session
Authentication: None
                  POST /services/shopping/v1/item/[session]/discount
                

Description

Use this API to apply a discount to a shopping session. This is an optional step, but if required, must be done after a shopping session has been created.

Request Parameters

Parameter Type Description
code string Required. The promo code entered by the user.

Response Parameters

Parameter Type Description
shopping_session_token string The unique ID of the shopping session.
cc_on_file bool Whether the credit card is stored on file. This will always be false.
item string The slug of the item to be purchased.
item_price string The original price of the item, before any discount is applied.
ownership string The ownership type that was requested, i.e. “buy” or “rent”.
quality string The quality. This will either be “hd” or “sd”.
discount_amount string The discount amount that will be applied to this purchase.
total_price string The amount that will be charged to the customer in this transaction.
currency string ISO 4217 currency code.
freebie bool Set to true if the purchase amount is zero.

Examples

Apply a Discount to an Existing Shopping Session

curl -i 'https://store.shift72.com/services/shopping/v1/item/ecf48cced219146c2087757954612373/discount' \
  -H 'x-auth-token: 97d41cf20d38457ab81651db5521f74f' \
  -H 'content-type: application/json;charset=UTF-8' \
  --data-binary '{"code":"TEST11"}'

Response: Success

HttpStatus: 200
{  
  "shopping_session_token":"ecf48cced219146c2087757954612373",
  "cc_on_file":false,
  "item":"/film/119",
  "item_price":"$6.49 NZD",
  "ownership":"rent",
  "quality":"hd",
  "discount_amount":"$0.71 NZD",
  "total_price":"$5.78 NZD",
  "currency":"NZD",
  "freebie":false
}

Response: Error - Promo Code Invalid

HttpStatus: 403
{  
  "error":"Discount code provided is invalid"
}

Response: Error - Promo Code Already Applied

Only one promo code can be applied per shopping session.

HttpStatus: 403
{  
  "error":"A discount has already been applied to this shopping session"
}

Response: Error - Shopping Session Timed Out

The shopping session that was created using the Create API API will be deleted after a period. This is currently set to 20 minutes.

HttpStatus: 403
{  
  "error":"Shopping session not found for provided shopping session token"
}

Response: Unauthorized

HttpStatus: 401
Summary: Request shopping feature toggle settings
Authentication: None
                  GET /services/shopping/feature_toggles
                

Description

Use this API to get the feature toggle settings for the Shopping service. The feature toggles are used to control if clients have access to features that are in beta. The feature toggles are not listed here as they are usually short lived and are only required for controlling access to features that are in beta testing.

Examples

Shopping Feature Toggles Request

curl -i 'https://store.shift72.com/services/shopping/feature_toggles'

Response: Success

HttpStatus: 200
{  
  "admin_discounts":true
}
Summary: Refund a purchase
Authentication: X-Auth Admin
                  POST /services/shopping/v1/refund
                

Description

Use this API to refund a purchase. You can choose to refund the user’s credit card through Stripe, or choose to only have the refund recorded. This API is only accessible to users who have the admin role. Refunds for orders recorded through Order History (Create) with a valid Stripe payment intent can be initiated through this API.

Request Parameters

Parameter Type Description
order_id number Required. The order ID.
reason string Optional. A reason the refund was given.
do_refund bool Required. True if the credit card is to be refunded.
datetime string Optional. The date and time, in ISO 8601 format, to record the refund. It will default to the current date and time if it’s not entered.

Response Parameters

Parameter Type Description
error string A message that provides more information about the error.

Examples

Refund the Purchase for Order 994

curl -i 'https://store.shift72.com/services/shopping/v1/refund' \
  -X POST \
  -H 'x-auth-token: 74aab4688deed1869417e78ec1f80b53' \
  -H 'content-type: application/json;charset=UTF-8' \
  --data-binary '{
    "order_id":994,
    "reason":"",
    "do_refund":true,
    "datetime":""
  }'

Response: Success

HttpStatus: 200
200

Response: Invalid Order ID

HttpStatus: 404
{
  "error":"Can not find the order"
}

Response: Order Already Refunded

HttpStatus: 404
{
  "error":"Refund for this order already exists"
}

Response: Cannot Specify Refund Date When Refunding Through Stripe

HttpStatus: 403
{
  "error":"Cannot do refund with custom datetime",
  "code":"cannot_refund_custom_datetime"
}

Response: Refunds are not enabled

Response: Refunds disabled
HttpStatus: 400
{
  "error": "Refund disabled"
}

Response: Unauthorized

HttpStatus: 401
Summary: Resend a purchase receipt
Authentication: X-Auth Admin
                  POST /services/shopping/v1/item/resend_receipt
                

Description

Use this API to resend a purchase receipt email. You can specify a different email address to the one that was used during the purchase. This API is only accessible to users who have the admin role.

Request Parameters

Parameter Type Description
order_id number Required. The order ID.
email string Optional. The email address for the email to be sent to.

Response Parameters

Parameter Type Description
error string A message that provides more information about the error.

Examples

Resend a Purchase Receipt Email for Order 994

curl -i 'https://store.shift72.com/services/shopping/v1/item/resend_receipt' \
  -X POST \
  -H 'x-auth-token: 74aab4688deed1869417e78ec1f80b53' \
  -H 'content-type: application/json;charset=UTF-8' \
  --data-binary '{  
    "order_id":994,
    "email":"user@example.com"
  }'

Response: Success

HttpStatus: 200
200

Response: Invalid Order ID

HttpStatus: 404
{
  "error":"Can not find the order"
}

Response: Unauthorized

HttpStatus: 401
Summary: Check the status of a purchase request
Authentication: X-Auth
                  POST /services/shopping/v1/item/[session]/status
                

Description

Use this API to check that status of a purchase. The purchase request may take some time as the request is asynchronous so use this API to periodically check the status of the purchase.

Response Parameters

Parameter Type Description
status string The status of the requested purchase.

Examples

Create a Shopping Session for Buying Film 73

curl -i 'https://store.shift72.com/services/shopping/v1/item/7553ba40e91d59efae9d01002bfa3535/status' \
  -X POST \
  -H 'x-auth-token: 97d41cf20d38457ab81651db5521f74f'

Response: Completed

HttpStatus: 200
{  
  "status":"completed"
}

Response: Shopping Session Timed Out

The shopping session that was created using the Create API API will be deleted after a period. This is currently set to 20 minutes.

HttpStatus: 403
{  
  "error":"Shopping session not found for provided shopping session token"
}

Response: Unauthorized

HttpStatus: 401