Customer

A customer in PayNow represents a user on your store.

To access the current customer's information using a customer token, use the Storefront Customer API.

Customers can be created in the customer section on the dashboard.

Endpoints

POST
/stores/{store.id}/customers
GET
/stores/{store.id}/customers
GET
/stores/{store.id}/customers/lookup
GET
/stores/{store.id}/customers/{customer.id}
PATCH
/stores/{store.id}/customers/{customer.id}
DELETE
/stores/{store.id}/customers/tokens
POST
/stores/{store.id}/customers/{customer.id}/tokens
DELETE
/stores/{store.id}/customers/{customer.id}/tokens
GET
/stores/{store.id}/customers/{customer.id}/command_delivery
POST
/stores/{store.id}/customers/{customer.id}/command_delivery
DELETE
/stores/{store.id}/customers/{customer.id}/command_delivery/{item.id}

The Customer object

Fields
Name
id
Type
flake
Tags
Description
id of the customer
Name
store_id
Type
flake
Tags
Description
id of the store this customer belongs to
Name
profile
Type
generic profile
Tags
NULLABLE
Description
the generic profile information for this customer
Name
steam_id
Type
string
Tags
NULLABLE
Description
the SteamID64 of this customer
Name
minecraft_uuid
Type
string
Tags
NULLABLE
Description
the Minecraft UUID of this customer
Name
steam
Type
steam profile
Tags
NULLABLE
Description
the basic Steam profile information for this customer
Name
minecraft
Type
minecraft profile
Tags
NULLABLE
Description
the basic Minecraft profile information for this customer
Name
name
Type
string
Tags
NULLABLE
Description
the name of the customer
Name
metadata
Type
object
Tags
NULLABLE
Description
a key value object containing arbitrary data for this customer
Name
created_by
Type
user
Tags
NULLABLE
Description
the user that created this customer. null when the customer was created by logging in to a hosted store.
Name
created_at
Type
timestamp
Tags
Description
timestamp of when the customer was created
Name
updated_by
Type
user
Tags
NULLABLE
Description
the user that most recently updated this customer
Name
updated_at
Type
timestamp
Tags
NULLABLE
Description
timestamp of when the customer was last updated

Steam Profile Structure

Fields
Name
id
Type
string
Tags
Description
the profile's SteamID64
Name
name
Type
string
Tags
NULLABLE
Description
the profile's display name
Name
avatar_url
Type
string
Tags
NULLABLE
Description
the profile's avatar url

Minecraft Profile Structure

Fields
Name
id
Type
string
Tags
Description
the profile's UUID
Name
name
Type
string
Tags
NULLABLE
Description
the profile's display name
Name
avatar_url
Type
string
Tags
NULLABLE
Description
the profile's Minecraft head avatar url

Generic Profile Structure

Fields
Name
id
Type
string
Tags
Description
the profile's unique identifier
Name
platform
Type
enum
Tags
Description
the profile provider platform
Allowed enum values
steam
minecraft
minecraft_offline
Name
name
Type
string
Tags
NULLABLE
Description
the profile's display name
Name
avatar_url
Type
string
Tags
NULLABLE
Description
the profile's avatar url

The Customer object

{
  "id": "150352880618967040",
  "store_id": "94688451781206016",
  "steam_id": "76561197960287930",
  "steam": {
    "id": "76561197960287930",
    "name": "Rabscuttle",
    "avatar_url": "https://avatars.akamai.steamstatic.com/c5d56249ee5d28a07db4ac9f7f60af961fab5426_full.jpg"
  },
  "name": "Rabscuttle",
  "metadata": {
    "example_key": "example value"
  },
  "created_by": {
    "id": "11084680073842688",
    "first_name": "Example",
    "last_name": "Exampleson"
  },
  "created_at": "2023-04-13T19:51:02.162046Z",
  "updated_by": {
    "id": "11084680073842688",
    "first_name": "Example",
    "last_name": "Exampleson"
  },
  "updated_at": "2023-04-14T06:11:18.8643Z"
}

Create Customer

Creates a new customer.

All fields are optional, which lets you create completely blank customers that can be edited for future use.

Parameters
Name
steam_id
Type
string?
Tags
OPTIONAL
Description
the SteamID64 for this customer. Must be unique to the store.
Name
minecraft_uuid
Type
string?
Tags
OPTIONAL
Description
the Minecraft UUID for this customer. Must be unique to the store.
Name
name
Type
string?
Tags
OPTIONAL
Description
the name of the customer (1 - 50 characters). If using a store with minecraft platform, you can just enter the name and a minecraft UUID will be fetched (and vice-versa).
Name
metadata
Type
object?
Tags
OPTIONAL
Description
the metadata for this customer. Must be an object with no more than 50 keys. Key names can be up to 40 characters, and values can be up to 500 characters.

Returns

Returns the newly created customer.

Request

customer_create

POST
/stores/{store.id}/customers

Response

{
  "id": "150510813361217536",
  "store_id": "94688451781206016",
  "steam_id": "76561199479391297",
  "steam": {
    "id": "76561197960287930",
    "name": "Rabscuttle",
    "avatar_url": "https://avatars.akamai.steamstatic.com/c5d56249ee5d28a07db4ac9f7f60af961fab5426_full.jpg"
  },
  "minecraft_uuid": null,
  "profile": {
    "id": "76561197960287930",
    "platform": "steam",
    "name": "Rabscuttle",
    "avatar_url": "https://avatars.akamai.steamstatic.com/c5d56249ee5d28a07db4ac9f7f60af961fab5426_full.jpg"
  },
  "name": null,
  "metadata": null,
  "created_by": {
    "id": "11084680073842688",
    "first_name": "Example",
    "last_name": "Exampleson"
  },
  "created_at": "2023-04-14T06:18:36.261990401Z",
  "updated_by": null,
  "updated_at": null
}

Get Customers

Returns all of the customers in the store.

Returns

Returns an array of customers.

Request

customer_read

GET
/stores/{store.id}/customers

Response

[
  {
    "id": "150352880618967040",
    "store_id": "94688451781206016",
    "steam_id": "76561197960287930",
    "steam": {
      "id": "76561197960287930",
      "name": "Rabscuttle",
      "avatar_url": "https://avatars.akamai.steamstatic.com/c5d56249ee5d28a07db4ac9f7f60af961fab5426_full.jpg"
    },
   "minecraft_uuid": null,
   "profile": {
     "id": "76561197960287930",
     "platform": "steam",
     "name": "Rabscuttle",
     "avatar_url": "https://avatars.akamai.steamstatic.com/c5d56249ee5d28a07db4ac9f7f60af961fab5426_full.jpg"
   },
    "name": "Rabscuttle",
    "metadata": {
      "example_key": "example value"
    },
    "created_by": {
      "id": "11084680073842688",
      "first_name": "Example",
      "last_name": "Exampleson"
    },
    "created_at": "2023-04-13T19:51:02.162046Z",
    "updated_by": {
      "id": "11084680073842688",
      "first_name": "Example",
      "last_name": "Exampleson"
    },
    "updated_at": "2023-04-14T06:11:18.8643Z"
  },
  {...},
  {...}
]

Lookup Customer

Returns a customer by its PayNow ID or alternative identifier.

Query Parameters
Name
id
Type
flake?
Tags
OPTIONAL
Description
a PayNow customer ID
Name
steam_id
Type
string?
Tags
OPTIONAL
Description
a SteamID64
Name
minecraft_uuid
Type
string?
Tags
OPTIONAL
Description
a Minecraft UUID
Name
name
Type
string?
Tags
OPTIONAL
Description
a customer name

Returns

Returns a customer if a valid ID was provided.

Request

customer_read

GET
/stores/{store.id}/customers/lookup

Response

{
  "id": "150352880618967040",
  "store_id": "94688451781206016",
  "steam_id": "76561197960287930",
  "steam": {
    "id": "76561197960287930",
    "name": "Rabscuttle",
    "avatar_url": "https://avatars.akamai.steamstatic.com/c5d56249ee5d28a07db4ac9f7f60af961fab5426_full.jpg"
  },
  "minecraft_uuid": null,
  "profile": {
    "id": "76561197960287930",
    "platform": "steam",
    "name": "Rabscuttle",
    "avatar_url": "https://avatars.akamai.steamstatic.com/c5d56249ee5d28a07db4ac9f7f60af961fab5426_full.jpg"
  },
  "name": "Rabscuttle",
  "metadata": {
    "example_key": "example value"
  },
  "created_by": {
    "id": "11084680073842688",
    "first_name": "Example",
    "last_name": "Exampleson"
  },
  "created_at": "2023-04-13T19:51:02.162046Z",
  "updated_by": {
    "id": "11084680073842688",
    "first_name": "Example",
    "last_name": "Exampleson"
  },
  "updated_at": "2023-04-14T06:11:18.8643Z"
}

Get Customer

Returns a customer by ID.

Returns

Returns a customer.

Request

customer_read

GET
/stores/{store.id}/customers/{customer.id}

Response

{
  "id": "150352880618967040",
  "store_id": "94688451781206016",
  "steam_id": "76561197960287930",
  "steam": {
    "id": "76561197960287930",
    "name": "Rabscuttle",
    "avatar_url": "https://avatars.akamai.steamstatic.com/c5d56249ee5d28a07db4ac9f7f60af961fab5426_full.jpg"
  },
  "minecraft_uuid": null,
  "profile": {
    "id": "76561197960287930",
    "platform": "steam",
    "name": "Rabscuttle",
    "avatar_url": "https://avatars.akamai.steamstatic.com/c5d56249ee5d28a07db4ac9f7f60af961fab5426_full.jpg"
  },
  "name": "Rabscuttle",
  "metadata": {
    "example_key": "example value"
  },
  "created_by": {
    "id": "11084680073842688",
    "first_name": "Example",
    "last_name": "Exampleson"
  },
  "created_at": "2023-04-13T19:51:02.162046Z",
  "updated_by": {
    "id": "11084680073842688",
    "first_name": "Example",
    "last_name": "Exampleson"
  },
  "updated_at": "2023-04-14T06:11:18.8643Z"
}

Update Customer

Updates a customer.

Parameters
Name
steam_id
Type
string?
Tags
OPTIONAL
Description
the SteamID64 for this customer. Must be unique to the store.
Name
minecraft_uuid
Type
string?
Tags
OPTIONAL
Description
the Minecraft UUID for this customer. Must be unique to the store.
Name
name
Type
string?
Tags
OPTIONAL
Description
the name of the customer (1 - 50 characters)
Name
metadata
Type
object?
Tags
OPTIONAL
Description
the metadata for this customer. Must be an object with no more than 50 keys. Key names can be up to 40 characters, and values can be up to 500 characters.

Returns

Returns the updated customer.

Request

customer_update

PATCH
/stores/{store.id}/customers/{customer.id}

Response

{
  "id": "150352880618967040",
  "store_id": "94688451781206016",
  "steam_id": "76561197960287930",
  "steam": {
    "id": "76561197960287930",
    "name": "Rabscuttle",
    "avatar_url": "https://avatars.akamai.steamstatic.com/c5d56249ee5d28a07db4ac9f7f60af961fab5426_full.jpg"
  },
  "minecraft_uuid": null,
  "profile": {
    "id": "76561197960287930",
    "platform": "steam",
    "name": "Rabscuttle",
    "avatar_url": "https://avatars.akamai.steamstatic.com/c5d56249ee5d28a07db4ac9f7f60af961fab5426_full.jpg"
  },
  "name": "Rabscuttle",
  "metadata": {
    "example_key": "example value"
  },
  "created_by": {
    "id": "11084680073842688",
    "first_name": "Example",
    "last_name": "Exampleson"
  },
  "created_at": "2023-04-13T19:51:02.162046Z",
  "updated_by": {
    "id": "11084680073842688",
    "first_name": "Example",
    "last_name": "Exampleson"
  },
  "updated_at": "2023-04-14T06:11:18.8643Z"
}

Customer Tokens

Customer tokens are used to access the Storefront API resources.

They can be used to remotely access the API for fetching store and product information in a customer context.

Customer tokens don't expire by default, but they can be manually invalidated either per customer or for all customers across the whole store.

Customer tokens can be created in the customer section on the dashboard. Select a customer and then click "Create token".

Create Customer Token

Creates a new token for a customer.

This token can be used to perform actions on the store as that customer.

Returns

Returns an object containing a token field.

Request

customer_update

POST
/stores/{store.id}/customers/{customer.id}/tokens

Response

{
  "token": "bDtsioCAvqriRbuvBA4fjqjbBApAzJo3jQ4w39LtroUfQcBkFaDAHGWdGxpMGRpkRFBf6w6"
}

Invalidate Customer Tokens

Invalidates all tokens created for a single customer, effectively logging them out.

Returns

Returns HTTP 204

Request

customer_update

DELETE
/stores/{store.id}/customers/{customer.id}/tokens

Response

HTTP 204

Invalidate All Tokens

Invalidates all customer tokens across the entire store, effectively logging them all out.

Returns

Returns HTTP 204

Request

store_update

customer_update

DELETE
/stores/{store.id}/customers/tokens

Response

HTTP 204

The InventoryItem object

An inventory item represents a product that is owned by a customer. When a customer buys something on your store, the product goes into their inventory as an inventory item.

Items can also be assigned and revoked from the customer's inventory. Items are automatically revoked when the payment is reversed (either by refund or chargeback).

Inventory items have different states depending on the product's commands and configuration. See the state field below for more details.

Fields
Name
id
Type
flake
Tags
Description
id of the item
Name
store_id
Type
flake
Tags
Description
id of the store this item belongs to
Name
customer
Type
customer
Tags
Description
the customer who owns this item
Name
order_customer
Type
customer
Tags
NULLABLE
Description
the customer who ordered this item
Name
order_id
Type
flake
Tags
NULLABLE
Description
id of the order that is related to this item
Name
order_line_id
Type
flake
Tags
NULLABLE
Description
id of the order line that is related to this item
Name
quantity_index
Type
integer
Tags
NULLABLE
Description
the quantity index of this item. Used if the order line contained multiple units.
Name
product
Type
partial product
Tags
Description
the product this inventory item represents
Name
state
Type
enum
Tags
Description
the state of the item
Allowed enum values
usable
item has been assigned, but has not been used yet
active
item is active
used
item has been used
revoked
item has been revoked
Name
expirable
Type
boolean
Tags
Description
whether this item has a duration and can expire
Name
gift
Type
boolean
Tags
Description
whether this item was a gift
Name
added_at
Type
timestamp
Tags
Description
timestamp of when this item was added to the customer's inventory
Name
added_by
Type
user
Tags
NULLABLE
Description
the user that added this item to the customer's inventory. null when the item was added from an order.
Name
active_at
Type
timestamp
Tags
NULLABLE
Description
timestamp of when this item was activated. Is populated after the item becomes active.
Name
expires_at
Type
timestamp
Tags
NULLABLE
Description
timestamp of when this item will expire. Is populated after the item becomes active.
Name
removed_at
Type
timestamp
Tags
NULLABLE
Description
timestamp of when this item was removed. Is populated after the item becomes used.
Name
revoked_at
Type
timestamp
Tags
NULLABLE
Description
timestamp of when this item was revoked. Is populated after the item becomes revoked.
Name
revoke_reason
Type
enum
Tags
NULLABLE
Description
the reason this item was revoked
Allowed enum values
admin
a store admin decided to manually revoke the item
refund
the item was refunded from the original order
chargeback
the customer initiated a chargeback
Name
revoked_by
Type
user
Tags
NULLABLE
Description
the user who revoked this item

Partial Product Structure

Contains a partial set fields that refer to a product

Fields
Name
id
Type
flake
Tags
Description
id of the product
Name
store_id
Type
flake
Tags
Description
the id of the store that this product belongs to
Name
version_id
Type
flake
Tags
Description
version id of the product
Name
slug
Type
string
Tags
Description
the url-safe identifier for the product, unique to the store
Name
name
Type
string
Tags
Description
the name the product

The InventoryItem object

{
  "id": "149643503939362817",
  "store_id": "94688451781206016",
  "customer": {
    "id": "150352880618967040",
    "store_id": "94688451781206016",
    "steam_id": "76561197960287930",
    "steam": {
      "id": "76561197960287930",
      "name": "Rabscuttle",
      "avatar_url": "https://avatars.akamai.steamstatic.com/c5d56249ee5d28a07db4ac9f7f60af961fab5426_full.jpg"
    },
    "name": "Rabscuttle",
    "metadata": {
      "example_key": "example value"
    },
    "created_at": "2023-04-10T19:51:02.162046Z",
    "updated_at": "2023-04-11T06:11:18.8643Z"
  },
  "order_customer": {
    "id": "150352880618967040",
    "store_id": "94688451781206016",
    "steam_id": "76561197960287930",
    "steam": {
      "id": "76561197960287930",
      "name": "Rabscuttle",
      "avatar_url": "https://avatars.akamai.steamstatic.com/c5d56249ee5d28a07db4ac9f7f60af961fab5426_full.jpg"
    },
    "name": "Rabscuttle",
    "metadata": {
      "example_key": "example value"
    },
    "created_at": "2023-04-10T19:51:02.162046Z",
    "updated_at": "2023-04-11T06:11:18.8643Z"
  },
  "order_id": "149643389770407936",
  "order_line_id": "149643389770407937",
  "quantity_index": 1,
  "product": {
    "id": "124249183568797696",
    "store_id": "94688451781206016",
    "version_id": "147121000780144640",
    "slug": "banana",
    "name": "Banana"
  },
  "state": "used",
  "expirable": true,
  "gift": false,
  "added_at": "2023-04-11T20:52:13.659206Z",
  "added_by": null,
  "active_at": "2023-04-11T21:52:53.66545Z",
  "expires_at": "2023-04-11T22:52:53.66545Z",
  "removed_at": "2023-04-11T22:53:55.763216Z",
  "revoked_at": null,
  "revoke_reason": null,
  "revoked_by": null
}

Get Customer Inventory

Returns all of the items in the customer's inventory.

Returns

Returns an array of inventory items.

Request

customer_inventory_manage

GET
/stores/{store.id}/customers/{customer.id}/command_delivery

Response

[
  {
    "id": "149643503939362817",
    "store_id": "94688451781206016",
    "customer": {
      "id": "150352880618967040",
      "store_id": "94688451781206016",
      "steam_id": "76561197960287930",
      "steam": {
        "id": "76561197960287930",
        "name": "Rabscuttle",
        "avatar_url": "https://avatars.akamai.steamstatic.com/c5d56249ee5d28a07db4ac9f7f60af961fab5426_full.jpg"
      },
      "name": "Rabscuttle",
      "metadata": {
        "example_key": "example value"
      },
      "created_at": "2023-04-10T19:51:02.162046Z",
      "updated_at": "2023-04-11T06:11:18.8643Z"
    },
    "order_customer": {
      "id": "150352880618967040",
      "store_id": "94688451781206016",
      "steam_id": "76561197960287930",
      "steam": {
        "id": "76561197960287930",
        "name": "Rabscuttle",
        "avatar_url": "https://avatars.akamai.steamstatic.com/c5d56249ee5d28a07db4ac9f7f60af961fab5426_full.jpg"
      },
      "name": "Rabscuttle",
      "metadata": {
        "example_key": "example value"
      },
      "created_at": "2023-04-10T19:51:02.162046Z",
      "updated_at": "2023-04-11T06:11:18.8643Z"
    },
    "order_id": "149643389770407936",
    "order_line_id": "149643389770407937",
    "quantity_index": 1,
    "product": {
      "id": "124249183568797696",
      "store_id": "94688451781206016",
      "version_id": "147121000780144640",
      "slug": "banana",
      "name": "Banana"
    },
    "state": "used",
    "expirable": true,
    "gift": false,
    "added_at": "2023-04-11T20:52:13.659206Z",
    "added_by": null,
    "active_at": "2023-04-11T21:52:53.66545Z",
    "expires_at": "2023-04-11T22:52:53.66545Z",
    "removed_at": "2023-04-11T22:53:55.763216Z",
    "revoked_at": null,
    "revoke_reason": null,
    "revoked_by": null
  },
  {...},
  {...}
]

Assign Inventory Item

Assigns a product to a customer's inventory.

Must provide either product_id or product_version_id. Will return multiple items if quantity is greater than 1.

Does not affect stock limits.

Parameters
Name
product_id
Type
flake?
Tags
OPTIONAL
Description
the id of the product to assign.
Name
product_version_id
Type
flake?
Tags
OPTIONAL
Description
the id of the product version to assign.
Used to assign a specific version of a product.
Name
quantity
Type
integer?
Tags
OPTIONAL
Description
the number of units to add (1 - 20 limit)

Returns

Returns an array of the newly created inventory items.

Request

customer_inventory_manage

POST
/stores/{store.id}/customers/{customer.id}/command_delivery

Response

[
  {
    "id": "150548885075402752",
    "store_id": "94688451781206016",
    "customer": {
      "id": "150352880618967040",
      "store_id": "94688451781206016",
      "steam_id": "76561197960287930",
      "steam": {
        "id": "76561197960287930",
        "name": "Rabscuttle",
        "avatar_url": "https://avatars.akamai.steamstatic.com/c5d56249ee5d28a07db4ac9f7f60af961fab5426_full.jpg"
      },
      "name": "Rabscuttle",
      "metadata": {
        "example_key": "example value"
      },
      "created_at": "2023-04-13T19:51:02.162046Z",
      "updated_at": "2023-04-14T06:11:18.8643Z"
    },
    "order_customer": null,
    "order_id": null,
    "order_line_id": null,
    "quantity_index": null,
    "product": {
      "id": "124249183568797696",
      "store_id": "94688451781206016",
      "version_id": "149702205245493248",
      "slug": "banana",
      "name": "Banana"
    },
    "state": "usable",
    "expirable": true,
    "gift": false,
    "added_at": "2023-04-14T08:49:53.265720572Z",
    "added_by": {
      "id": "11084680073842688",
      "first_name": "Example",
      "last_name": "Exampleson"
    },
    "active_at": null,
    "expires_at": null,
    "removed_at": null,
    "revoked_at": null,
    "revoke_reason": null,
    "revoked_by": null
  }
]

Revoke Inventory Item

Revokes an item from the customer's inventory.

Returns

Returns HTTP 204

Request

customer_inventory_manage

DELETE
/stores/{store.id}/customers/command_delivery/{item.id}

Response

HTTP 204

Customer

Endpoints

Fields

Fields

Fields

Fields

The Customer object

Parameters

Returns

Request

Response

Returns

Request

Response

Query Parameters

Returns

Request

Response

Returns

Request

Response

Parameters

Returns

Request

Response

Returns

Request

Response

Returns

Request

Response

Returns

Request

Response

Fields

Fields

The InventoryItem object

Returns

Request

Response

Parameters

Returns

Request

Response

Returns

Request

Response