Storefront Product

Products are what your customers see when they visit your store. They have a name, price, thumbnail, and many other properties you can use to enhance your store's display.

IMPORTANT: To properly display any relevant VAT/GST taxes, and for anti-fraud purposes, you are required to include the customer's IP address OR country code (preferred, in ISO 3166-1 alpha-2 format) in the request headers if you are proxying the requests through your server (in cases such as server-side rendering).

Endpoints

GET
/store/products
GET
/store/products/{product.id}
GET
/store/products/{product.slug}

Request Headers
Name
x-paynow-store-id
Type
flake
Tags
REQUIRED
Description
the ID of your store
Name
Authorization
Type
customer auth?
Tags
OPTIONAL
Description
the token of your customer prefixed with customer if logged in, more information here
Name
x-paynow-customer-ip
Type
string
Tags
Description
the IP address (IPv4 or IPv6) of the customer.
Name
x-paynow-customer-countrycode
Type
string
Tags
Description
the customer's country code in ISO 3166-1 alpha-2 format. If you're using Cloudflare, you can use the value of CF-IPCountry header from the request of your customer.
You need to include either x-paynow-customer-ip or x-paynow-customer-countrycode if the requests are not being made from the customer's browser.

The Product object

Fields
Name
id
Type
flake
Tags
Description
id of the product
Name
store_id
Type
flake
Tags
Description
id of the store this product belongs to
Name
slug
Type
string
Tags
Description
the url-safe identifier for the product, unique to the store
Name
image_url
Type
string
Tags
NULLABLE
Description
a url to the thumbnail image for the product
Name
name
Type
string
Tags
Description
the name of the product
Name
description
Type
string
Tags
Description
the full-length description of the product
Name
enabled
Type
boolean
Tags
Description
a boolean signifying if the product is enabled. This will always be true.
Name
sort_order
Type
integer
Tags
Description
the sort order value of this product in ascending order.
Name
price
Type
integer
Tags
Description
the price of this product in zero-decimal format (where "$10.00" is 1000)
Name
allow_one_time_purchase
Type
boolean
Tags
Description
whether this product can be purchased one time (without subscribing)
Name
allow_subscription
Type
boolean
Tags
Description
whether this product can be subscribed to
Name
subscription_interval_value
Type
integer
Tags
Description
the interval value at which this product will renew when subscribed
Name
subscription_interval_scale
Type
enum
Tags
Description
the interval scale at which this product will renew when subscribed. Can be one of day, week, month, year
Name
stock
Type
stock limit
Tags
NULLABLE
Description
the latest stock availability/limits for this product. Will be null if the store has this information disabled for customer view.
Name
pricing
Type
pricing
Tags
NULLABLE
Description
the pricing details for the specified product. Includes estimated VAT and active sales.
We recommend to show your customers the applied VAT percentage and the VAT local name.
Name
tags
Type
product tag
Tags
Description
an array of tags that this product belongs to
Name
created_at
Type
timestamp
Tags
Description
timestamp of when the product was created
Name
updated_at
Type
timestamp
Tags
NULLABLE
Description
timestamp of when the product was last updated

Stock Limit Structure

Fields
Name
available_to_purchase
Type
boolean
Tags
Description
whether the product is available to purchase (all stock limits met)
Name
customer_available
Type
integer
Tags
NULLABLE
Description
the remaining stock available for the current customer

Pricing Structure

Fields
Name
active_sale
Type
active sale object
Tags
NULLABLE
Description
the active sale object if a sale is active
Name
sale_value
Type
integer
Tags
NULLABLE
Description
the total sale value applied to the final price
Name
vat_rate
Type
vat rate object
Tags
NULLABLE
Description
the estimated VAT rate information
Name
price_original
Type
integer
Tags
Description
the price before applying all taxes and discounts
Name
price_final
Type
integer
Tags
Description
the final price after applying all taxes and discounts (same as price field on the Product object)

Active Sale Structure

Fields
Name
id
Type
flake
Tags
Description
id of the sale
Name
name
Type
string
Tags
Description
name of the sale
Name
discount_type
Type
enum
Tags
Description
the type of discount this sale applies
Allowed enum values
percent
discount_amount applies as a percent
amount
discount_amount applies as an absolute amount
Name
discount_amount
Type
integer
Tags
Description
the discount amount this sale applies.
If discount_type is percent, then this is interpreted as multiples of 10 basis points (where 1000 is 100.0%)
If discount_type is amount, then this is interpreted as an absolute amount (where 1000 is $10.00)
Name
minimum_order_value
Type
integer
Tags
Description
the minimum order value required for the sale to be applied
Name
begins_at
Type
timestamp
Tags
Description
timestamp of when the sale started
Name
ends_at
Type
timestamp
Tags
NULLABLE
Description
timestamp of when the sale ends

VAT Rate Structure

Fields
Name
country_code
Type
string
Tags
Description
the country code (ISO 3166-1 alpha-2) this VAT applies to
Name
country_name
Type
string
Tags
Description
the full country name in English associated with this VAT rate
Name
currency
Type
string
Tags
Description
the currency of the country this VAT applies to
Name
vat_abbreviation
Type
string
Tags
Description
the local VAT abbreviation in local language
Name
vat_local_name
Type
string
Tags
Description
the full name of the VAT in local language
Name
eu_member_state
Type
boolean
Tags
Description
signifies if the associated country is a member of the EU
Name
percentage
Type
integer
Tags
Description
the percentage of the VAT

Product Tag Structure

Fields
Name
id
Type
flake
Tags
Description
id of the tag
Name
slug
Type
string
Tags
Description
the url-safe identifier for the tag, unique to the store
Name
name
Type
string
Tags
Description
the name the tag

The Product object

{
	"id": "214540104499212288",
	"store_id": "208289304403783680",
	"slug": "2x-trio-500-tokens",
	"image_url": null,
	"name": "2x Trio - 500 Tokens",
	"description": "<p>Upon purchasing this product you receive 500 tokens.</p>",
	"enabled": true,
	"price": 1814,
	"sort_order": 0,
	"allow_one_time_purchase": true,
	"allow_subscription": true,
	"subscription_interval_value": 1,
	"subscription_interval_scale": "month",
	"stock": {
		"available_to_purchase": true,
		"customer_available": 1
	},
	"pricing": {
		"active_sale": {
			"id": "221398701879345152",
			"name": "cool sale",
			"discount_type": "percent",
			"discount_amount": 250,
			"minimum_order_value": 0,
			"begins_at": "2023-09-30T22:00:00Z",
			"ends_at": "2024-01-31T23:00:00Z"
		},
		"sale_value": 374,
		"vat_rate": {
			"country_code": "CZ",
			"country_name": "Czech Republic",
			"currency": "CZK",
			"vat_abbreviation": "DPH",
			"vat_local_name": "Daň z přidané hodnoty",
			"eu_member_state": true,
			"percentage": 21
		},
		"price_original": 1499,
		"price_final": 1814
	},
	"tags": [
		{
			"id": "214540052082991104",
			"slug": "test",
			"name": "test"
		}
	],
	"created_at": "2023-10-07T22:48:08.842234Z",
	"updated_at": "2023-11-18T12:57:48.646287Z"
}

Get Products

Returns all products in the store.

Returns

Returns an array of products.

Request

product_read

GET
/store/products

Response

[
{
	"id": "117390520375844864",
	"store_id": "94688451781206016",
	"slug": "super-special-kit",
	"image_url": "https://example.paynow.gg/image.webp",
	"name": "Super Special Kit",
	"description": "Become the envy of your friends with this super special kit. Batteries not included.",
	"price": 699,
	"allow_one_time_purchase": true,
	"allow_subscription": true,
	"subscription_interval_value": 1,
	"subscription_interval_scale": "month",
	"stock": {
	"available_to_purchase": true
},
	"tags": [
{
	"id": "103968177980973056",
	"slug": "kits",
	"name": "Kits"
}
	],
	"created_at": "2023-04-12T20:50:23.069562Z",
	"updated_at": "2023-04-13T21:48:26.264271Z"
},
{...},
{...}
]

Get Product

Returns a product located by its id or slug field.

Returns

Returns a product if a valid identifier was provided.

Request

product_read

GET
/store/products/{product.id}
GET
/store/products/{product.slug}

Response

{
	"id": "117390520375844864",
	"store_id": "94688451781206016",
	"slug": "super-special-kit",
	"image_url": "https://example.paynow.gg/image.webp",
	"name": "Super Special Kit",
	"description": "Become the envy of your friends with this super special kit. Batteries not included.",
	"price": 699,
	"allow_one_time_purchase": true,
	"allow_subscription": true,
	"subscription_interval_value": 1,
	"subscription_interval_scale": "month",
	"stock": {
	"available_to_purchase": true
},
	"tags": [
{
	"id": "103968177980973056",
	"slug": "kits",
	"name": "Kits"
}
	],
	"created_at": "2023-04-12T20:50:23.069562Z",
	"updated_at": "2023-04-13T21:48:26.264271Z"
}

Storefront Product

Endpoints

Request Headers

Fields

Fields

Fields

Fields

Fields

Fields

The Product object

Returns

Request

Response

Returns

Request

Response