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.

Request Parameters

Parameter Type Description
enabled bool Optional. Determines if the promo code is enabled or disabled.
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.
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 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.

Response Parameters

Returns Promo Code.

Examples

Create a New Promo Code

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: 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 '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. This should always be “hd”.

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 always be “hd”.
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 '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 always be “hd”.
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 '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.

Response Parameters

Parameter Type Description
admin_discounts bool Deprecated. No longer used.

Examples

Shopping Feature Toggles Request

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

Response: Success

HttpStatus: 200
{  
  "admin_discounts":true
}
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 Deprecated. This will always be hd.
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: Attempt to complete the purchase using Stripe
Authentication: X-Auth
                  POST /services/shopping/v1/item/[session]/purchase_stripe
                

Description

Use this API to complete a purchase by charging the user’s credit card. For improved security, the credit card details are not sent to the SHIFT72 API’s. Instead you will need to obtain a Stripe token by using stripe.js. The purchase request may take some time as the request is asynchronous. Use the Status API to periodically check the status.

Request Parameters

Parameter Type Description
token string Required. The Stripe token obtained by using stripe.js.

Response Parameters

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

Examples

Complete the Purchase for a Previously Created Shopping Session

curl 'https://store.shift72.com/services/shopping/v1/item/7553ba40e91d59efae9d01002bfa3535/purchase_stripe' \
  -H 'x-auth-token: 97d41cf20d38457ab81651db5521f74f' \
  -H 'content-type: application/json;charset=UTF-8' \
  --data-binary '{"token":"tok_6GWjril6e46ZpP"}'

Response: Processing

The purchase request may take some time as the request is asynchronous. Use the Status API to periodically check the status.

HttpStatus: 202
{  
  "status":"processing"
}

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
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.

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: 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