SHIFT72 API Documentation

Promo Code

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

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

Promo Code (Create)

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

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": []
}

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

Response: Unauthorized

HttpStatus: 401

Promo Code (Delete)

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

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

Promo Codes (Search)

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

Promo Code (Update)

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

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

Subscriptions (Delete)

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"
}

Subscriptions (Delete) - Admin

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"
}

Subscriptions

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

Subscriptions - Admin

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

Tax Configurations Create

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

Tax Configurations Delete

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

Tax Configurations Get

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

Tax Configurations Get All

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

Tax Configurations Update

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

Order History (Get)

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

Order History (Create)

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

Cancel

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

Configuration

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"
}

Create

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

Discount

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
}

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

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

Feature Toggles

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
}

Refund

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

Resend Receipt

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

Status

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

Shopping Service

Description

Response Parameters

Examples

Show the Details of Promo Code 19

Response: Success

Response: Unauthorized

Description

Request Parameters

Response Parameters

Examples

Create a New Promo Code

Response: Success

Response: Promo Code Already Used

Response: Unauthorized

Description

Response Parameters

Examples

Delete Promo Code 22

Response: Success

Response: Error

Response: Unauthorized

Description

Query String Request Parameters

Pagination Header Response Parameters

Response Parameters

Examples

Search for Matches on “test”

Response: Success

Response: Unauthorized

Description

Request Parameters

Response Parameters

Examples

Update Promo Code 19

Response: Success

Response: Unauthorized

Description

Response Parameters

Examples

Response: Success

Response: Subscription Not Found

Response: Subscription Already Cancelled

Description

Response Parameters

Examples

Response: Success

Response: Unauthorized

Response: Subscription Not Found

Response: Subscription Already Cancelled

Description

Response Parameters

Examples

Response: Success

Response: Unauthorized

Description

Response Parameters

Examples

Response: Success

Response: Unauthorized

Description

Request Parameters

Response Parameters

Examples

Create a Tax Configuration for New Zealand

Response: Success

Response: Tax Configuration with Given Country Code Already Exists

Response: Country Code Parameter Missing

Response: Tax Type Parameter Missing

Response: Tax Percentage Parameter Missing

Response: Tax Number Parameter Missing

Response: Tax Configuration Failed to Save

Response: Unauthorized

Description

Examples

Delete Tax Configuration 99

Response: Success

Response: Tax Configuration Not Found

Response: Unauthorized

Description