# Authentication
Source: https://docs.covver.io/api-reference/auth
Covver's authentication is based on OAuth.
To authenticate your API requests, you will need to:
Get your `clientId` and `clientSecret` from Covver's dev team ([rnd@covver.io](mailto:rnd@covver.io)).
Use your credentials to create an `accessToken` (see below).
Add the `accessToken` in `Bearer Authentication` for each API Request.
## Creating Access Tokens
There are 2 ways to create access tokens:
* [Using your ClientID and ClientSecret](/api-reference/auth/create-oauth-tokens)
* [Using a refresh token](/api-reference/auth/refresh-token)
# Create OAuth Tokens
Source: https://docs.covver.io/api-reference/auth/create-oauth-tokens
post /api/ext/v1/oauth/tokens
Create an access token and a refresh token
Send your `clientId` and `clientSecret`, and receive a short-lived (10 minutes) `accessToken` and a long-lived (30 days) `refreshToken`.
# Refresh the access token
Source: https://docs.covver.io/api-reference/auth/refresh-token
post /api/ext/v1/oauth/refresh-token
Uses a refresh token to create an access token
You received your `refreshToken` using the [Create OAuth Tokens](/api-reference/auth/create-oauth-tokens) API\
Now you can use it to receive a short-lived (10 minutes) `accessToken`
# Company Swag Catalog Overview
Source: https://docs.covver.io/api-reference/catalog
Get information about collections, products, variants and images to display in an eCommerce store
The catalog is organized in the following manner:
* Companies (AKA customers)
* Collections (AKA stores)
* Products (For example, a t-shirt)
* Variants (For example, a t-shirt in a specific size and color)
## APIs
* [Create a company](/api-reference/catalog/create-company)
* [List collections](/api-reference/catalog/list-collections)
* [List products in a collection](/api-reference/catalog/list-a-collections-products)
* [Get a full product with variants](/api-reference/catalog/get-product)
* [Update a product](/api-reference/catalog/update-product)
* [Create a collection](/api-reference/catalog/create-collection)
* [Get collection status](/api-reference/catalog/get-collection-status)
* [Personalize a collection for a specific user](/api-reference/catalog/personalize-collection)
# Create a new collection
Source: https://docs.covver.io/api-reference/catalog/create-collection
post /api/ext/v1/collection
Automatically create a branded collection from a logo
Use this API if you want to create the collections via API.
You could also create them manually from your partner dashboard
Store creation takes about 30 seconds. Use the [Get collection status](/api-reference/designs/get-collection-status) API to poll for the status
Omit companyId if you want to create a new company as well
# Create a company (deprecated)
Source: https://docs.covver.io/api-reference/catalog/create-company
post /api/ext/v1/companies
Create a company (deprecated)
# Deprecated: please create companies from the partner dashboard
# Get the status of a collection
Source: https://docs.covver.io/api-reference/catalog/get-collection-status
get /api/ext/v1/collection/{collectionId}/status
Store creation takes about 30 seconds. Poll this API every few seconds to know when the collection is ready with all products and images
# Get Product
Source: https://docs.covver.io/api-reference/catalog/get-product
get /api/ext/v1/collection/{collectionId}/product/{productId}
Get a detailed product by ID
## International pricing
NOTE! Some products have a `priceDeltaByCountry` field that will affect the price of the product when shipped internationally.
If you pass `countryCode` when getting the product you will get the price after applying the delta. If you don't pass `countryCode` you should apply the delta yourself based on the recipient's address
## Localization (optional)
Use the accept-language header to get translated strings.
Supported locales:
* en-US (default locale)
* fr-FR
* fr-CA
* es-ES
* es-MX
* en-AU
* en-GB
```
Examples:
- Accept-Language: *
- Accept-Language: fr
- Accept-Language: fr-FR
- Accept-Language: fr-FR, fr;q=0.9, en;q=0.8, *;q=0.5
```
# List a Collection Products
Source: https://docs.covver.io/api-reference/catalog/list-a-collection-products
get /api/ext/v1/collection/{collectionId}/products
List a collection products by collection ID
## Localization (optional)
Use the accept-language header to get translated strings.
Supported locales:
* en-US (default locale)
* fr-FR
* fr-CA
* es-ES
* es-MX
* en-AU
* en-GB
```
Examples:
- Accept-Language: *
- Accept-Language: fr
- Accept-Language: fr-FR
- Accept-Language: fr-FR, fr;q=0.9, en;q=0.8, *;q=0.5
```
## Statuses
Multiple statuses can be sent as comma separated values
For a personalized collection, poll this API with the same data until `status !== 'Pending'` (\~20 seconds)
# List Collections
Source: https://docs.covver.io/api-reference/catalog/list-collections
get /api/ext/v1/collections
List all account collections
# Personalize a collection
Source: https://docs.covver.io/api-reference/catalog/personalize-collection-deprecated
post /api/ext/v1/collection/{collectionId}/personalize
Personalize an existing collection for a specific store user (deprecated)
The personalization takes around 15-20 seconds and only works on personalizable collections.
The response will return:
* a `sha` that is used for displaying the images (see [personalization guide](/guides/personalization))
* a `fields` property that is used when submitting personalized orders (see [personalization guide](/guides/personalization))
# Update Product
Source: https://docs.covver.io/api-reference/catalog/update-product
put /api/ext/v1/collection/{collectionId}/product/{productId}
Update a product status and add notes
# Changelog
Source: https://docs.covver.io/api-reference/change-log
Changelog of API changes
Subscribe to notifications by putting in your information [here](https://www.covver.io/api-notifications)
## July 29th, 2025
* Added note about Mexico RFC number
## July 10th, 2025
* Fixed `validateOrder` API authorization
* Deprecated `createCompany` API
## January 27th, 2025
* Added `priceDeltaByCountry` to get product endpoint
## December 30th, 2024
* Added `trackingNumber` and `allShipments` to order status
## September 22nd, 2024
* Added `status` and `notes` to product related API endpoints
## September 2nd, 2024
* Added supported locales to the locales list for getProduct and listProducts endpoint
* The supported locales are "fr-FR", "fr-CA", "es-ES", "es-MX", "en-AU", "en-GB" and "en-US" is the default.
## August 18th, 2024
* Added `countryCode` to `getProduct`'s query
* Will affect item pricing in case there is DDP/Shipping costs breakdown
## August 13th, 2024
* Added accept-language header to getProduct and listProducts endpoint
* Only "en-US", "fr-FR", and "es-ES" locales are supported at the moment
## August 4th, 2024
* Added mandatory taxNumber fields for China, Italy, and South Korea
## July 28th, 2024
* Added a `descriptionV2` and `sizeChartTable` to the get product endpoint. `descriptionV2` is the description without the size chart HTML and the `sizeChartTable` is the size chart HTML.
## July 22nd, 2024
* Added an API to update a product. Can update the product status and also notes on the product
* Added a sizeChartImages to the get product endpoint
## July 17th, 2024
Added an optional `personalizationsUsed` field on the collection object that corresponds to all of the data needed to create all the personalized products in this collection.
This field will only be populated in personalized collections.
## July 10th, 2024
Introducing `status` field for products.
The Draft product status enables a design review process where products can be added in draft mode and set to active only after approval.
In the API, only active products, which are available for sale, should be retrieved.
* New products in stores are created in `Draft` status.
* Added `status` to list products endpoint in order to filter products by status. By default, only active products are returned.
* Product with `Draft` status will *fail on place order* endpoint.
## July 3rd, 2024
* Added `creationStatus` to list products and get product endpoints
* Made `companyId` mandatory when creating webhooks
## June 24th, 2024
* Added `isVipOrder` to placeOrder API
# Orders Overview
Source: https://docs.covver.io/api-reference/orders
Place and list orders
## Orders
Orders are made of order items, each one specifying a variant and a quantity
## Order Notifications
Store users receive the following email notifications from Covver:
* Order confirmation
* Order is on its way
## Order APIs
* [Validate address](/api-reference/orders/validate-order)
* [Place an Order](/api-reference/orders/place-order)
* [List Orders](/api-reference/orders/list-orders)
* [Get Order Status](/api-reference/orders/get-order-status)
# Order status
Source: https://docs.covver.io/api-reference/orders/get-order-status
get /api/ext/v1/collection/{collectionId}/orders/{orderId}
Get the status of an order
Partners must pass in the companyId field in the body
# List Orders
Source: https://docs.covver.io/api-reference/orders/list-orders
post /api/ext/v1/collection/{collectionId}/orders/get
List all orders by collection ID
Date range filter is inclusive of both start and end dates and only filters via the day and not the time of day
Partners must pass in the companyId field in the body
# List shipping regions
Source: https://docs.covver.io/api-reference/orders/list-shipping-regions
get /api/ext/v1/shipping-regions
# Place Order
Source: https://docs.covver.io/api-reference/orders/place-order
post /api/ext/v1/collection/{collectionId}/orders
Place a new order
See [List of countries](/api-reference/orders/list-shipping-regions)
Pass in the user's details for personalized items. See [personalization guide](/guides/personalization) for more details
Partners must pass in the companyId field in the body
## International pricing
NOTE! Some products have a `priceDeltaByCountry` field that will affect the price of the product when shipped internationally.
If you pass `countryCode` when getting the product you will get the price after applying the delta. If you don't pass `countryCode` you should apply the delta yourself based on the recipient's address
## Tax number
For Brazil, Mexico, China, Italy, and South Korea you must pass in an additional taxNumber field.
For Brazil the tax number field must pass regex validation as follows
```javascript theme={null}
new RegExp(`^\\d{3}\\.\\d{3}\\.\\d{3}-\\d{2}$`).test(taxNumber)
```
For Mexico the pattern is 13 characters (4 letters followed by 6 digits and 3 alphanumeric characters).
```javascript theme={null}
new RegExp(`^[A-Za-z]{4}\\d{6}[A-Za-z0-9]{3}$`).test(taxNumber)
```
For China, Italy, and South Korea there is no validation run on the taxNumber field.
## Personalization
To order a product with personalization the personalized product must first be created via the getProduct or listProducts endpoints
## CustomAttributes
Custom attribute field is deprecated. Please use the taxNumber field instead
# Validate an order
Source: https://docs.covver.io/api-reference/orders/validate-order
post /api/ext/v1/collection/{collectionId}/orders/validate-order
Validate an order
This endpoint validates
* The province is correct for the provided country
* The variants can be shipped to the provided country
* The phone number is valid
* The zip code is valid
* The taxNumber field
* It is supposed to be there for the provided country
* It is formatted correctly and passes regex validation
This endpoint does not currently check the validity of the address itself.
Phone number validation is done with [libphonenumber-js](https://www.npmjs.com/package/libphonenumber-js).
[Here](https://catamphetamine.gitlab.io/libphonenumber-js/) is a demo page of the phone validation for further testing.
Partners must pass in the companyId field in the body
## Tax number
For Brazil, Mexico, China, Italy, and South Korea you must pass in an additional taxNumber field.
For Brazil the tax number field must pass regex validation as follows
```javascript theme={null}
new RegExp(`^\\d{3}\\.\\d{3}\\.\\d{3}-\\d{2}$`).test(taxNumber)
```
For Mexico the pattern is 13 characters (4 letters followed by 6 digits and 3 alphanumeric characters).
```javascript theme={null}
new RegExp(`^[A-Za-z]{4}\\d{6}[A-Za-z0-9]{3}$`).test(taxNumber)
```
For China, Italy, and South Korea there is no validation run on the taxNumber field.
## CustomAttributes
Custom attribute field is deprecated. Please use the taxNumber field instead
# People Overview
Source: https://docs.covver.io/api-reference/people
Manage people who have access to the store, and manage their gifts and credits
## People = store users
People log in to the store using passwordless authentication, via a code sent to their email.
## Gifts and credits
Covver offers 2 types of stores:
* Prices are hidden from people
* Allocate gifts to allow people to order up to a certain amount of items
* Prices are visible to people
* Allocate credits to allow people to order up to a certain total price
* Stores with "payment checkout" enabled allow people to pay with CC or ACH for items that exceed their available credits
## People APIs
* [Create People](/api-reference/people/create-people)
* [List People](/api-reference/people/list-people)
* [Delete People](/api-reference/people/delete-people)
## Credit/gifts APIs
* [Reward credits/gifts](/api-reference/people/reward-credits)
* [Withdraw credits/gifts](/api-reference/people/withdraw-credits)
# Create People
Source: https://docs.covver.io/api-reference/people/create-people
post /api/ext/v1/people
Create people
You can also pass an optional parameter to specify how much credits/gifts to reward them
# Delete People
Source: https://docs.covver.io/api-reference/people/delete-people
delete /api/ext/v1/people
Delete people
Deleting people removes them from the system, and withdraws all outstanding credits/gifts balance they have.
# List People
Source: https://docs.covver.io/api-reference/people/list-people
post /api/ext/v1/people/get
List people in a collection
# Reward Credits/Points/Gifts
Source: https://docs.covver.io/api-reference/people/reward-credits
post /api/ext/v1/people/reward
Reward your people with credits/points or gifts
The type of reward is determined by the collection - whether it's a gift store, or a credits store
# Withdraw Credits/Points/Gifts
Source: https://docs.covver.io/api-reference/people/withdraw-credits
post /api/ext/v1/people/withdraw
Withdraw credits/points or gifts from your people
The type of reward is determined by the collection - whether it's a gift store, or a credits store
If you withdraw more credits/gifts than a person has, their balance will be 0
If you want to withdraw all credits/gifts, just pass a very high amount
# Webhook overview
Source: https://docs.covver.io/api-reference/webhooks
Receive webhook notifications about events in the Covver backend
## Setup
Contact [devsupport@covver.io](mailto:devsupport@covver.io) to setup a webhook destination URL
## Webhook events
```ts theme={null}
enum CovverWebhookEventType {
// Collection events
CollectionCreated = 'CollectionCreated',
CollectionDeleted = 'CollectionDeleted',
CollectionUpdated = 'CollectionUpdated',
// Product events
ProductCreated = 'ProductCreated',
ProductHidden = 'ProductHidden',
ProductShown = 'ProductShown',
ProductUpdated = 'ProductUpdated',
// Order events
OrderPlaced = 'OrderPlaced',
OrderConfirmed = 'OrderConfirmed',
OrderFulfilled = 'OrderFulfilled',
}
```
## Webhook format
All Webhooks are sent as a POST message and have this format:
```ts theme={null}
interface CovverWebhookEvent {
type: CovverWebhookEventType;
data: any;
}
```
## Webhook signature
All Webhooks include a `covverSignature` header to validate that the webhook is indeed coming from us as well as `covverIdempotencyKey` which is a unique key sent out per webhook.
Webhooks are signed using the code below where the secret is your client secret and the payload is the body of the POST request
```ts theme={null}
import { createHmac } from 'crypto';
function validatePayload(headers, payload) {
const signature = createHmac('sha256', secret)
.update(JSON.stringify(payload), 'utf8')
.digest('base64');
return headers['covverSignature'] === signature;
}
```
## Note
In subsequent webhook docs when we mention PersonalizationFieldsType we are referring to
```ts theme={null}
type PersonalizationFieldsType {
anniversary: {
decade: string;
hundreds: string;
month: number;
monthPadded: string;
ordinal: string;
year: number;
years: number;
yearsPadded: string;
zodiac: string;
elapsed: string;
},
birth: {
decade: string;
hundreds: string;
month: number;
monthPadded: string;
ordinal: string;
year: number;
years: number;
yearsPadded: string;
zodiac: string;
elapsed: string;
},
name: {
first: string;
firstNameInitials: string;
firstPossessive: string;
initials: string;
last: string;
lastNameInitials: string
},
work: {
department: string;
location: string;
}
}
```
# Collection created webhook event
Source: https://docs.covver.io/api-reference/webhooks/collection-created
Webhook data sent when a new collection is created
## Webhook data
```ts theme={null}
type CollectionCreatedData {
id: string;
title: string;
description: string;
slug: string;
deletedAt?: string | null;
}
```
## Example Webhook data
```ts theme={null}
{
"id": "a75337b0-f730-4522-97ab-3fd622d43f27",
"title": "Test Swag Store",
"slug": "test-swag-store",
"description": "Cool new store!",
"title": "Test Swag Store",
}
```
# Collection deleted webhook event
Source: https://docs.covver.io/api-reference/webhooks/collection-deleted
Webhook data sent when a new collection is deleted
## Webhook data
```ts theme={null}
type CollectionDeletedData {
id: string;
title: string;
slug: string;
description: string;
deletedAt: string;
}
```
## Example Webhook data
```ts theme={null}
{
"id": "a75337b0-f730-4522-97ab-3fd622d43f27",
"title": "Test Swag Store",
"slug": "test-swag-store",
"title": "Test Swag Store",
"description": "Cool new store!",
"deletedAt": "2024-01-01 15:45:25.932562",
}
```
# Collection updated webhook event
Source: https://docs.covver.io/api-reference/webhooks/collection-updated
Webhook data sent when a new collection is updated
## Webhook data
```ts theme={null}
type CollectionUpdatedData {
id: string;
title: string;
slug: string;
description: string;
deletedAt?: string | null
}
```
## Example Webhook data
```ts theme={null}
{
"id": "a75337b0-f730-4522-97ab-3fd622d43f27",
"title": "Test Swag Store",
"slug": "test-swag-store",
"title": "Test Swag Store",
"description": "Cool new store!",
}
```
# Create webhook
Source: https://docs.covver.io/api-reference/webhooks/create-webhook
post /api/ext/v1/webhook
Create a new webhook
# Delete webhook
Source: https://docs.covver.io/api-reference/webhooks/delete-webhook
delete /api/ext/v1/webhook/{id}
Delete a webhook
# List webhooks
Source: https://docs.covver.io/api-reference/webhooks/list-webhooks
get /api/ext/v1/webhook
Lists all webhooks
# Order confirmed webhook event
Source: https://docs.covver.io/api-reference/webhooks/order-confirmed
Webhook data sent when the order is confirmed
## Webhook data
```ts theme={null}
type OrderConfirmedData {
id: string;
createdAt: string;
orderNumber: string;
externalId?: string;
orderLineItems: {
id: string;
title: string;
price: number;
quantity: number;
// @deprecated, please use image.url
imageUrl: string,
image: { url: string; },
productId: string;
productTitle: string;
variantId: string;
variantTitle: string;
personalizations?: Partial
sha?: string;
}[]
}
```
## Example Webhook data without personalizations
```ts theme={null}
{
"id": "9a862a01-5e27-4961-ac1c-643de3ac07db",
"createdAt": "2024-01-01 15:45:25.932562",
"orderNumber": "123",
"orderLineItems": [
{
"id": "4251d65d-fab8-46de-908b-204c02ee32f0",
"title": "CamelBak Eddy 25oz Bottle Tritan - Clear / Large",
"price": 54,
"quantity": 1,
// @deprecated, please use image.url
"imageUrl": "https://media.covver.io/image/camelbak-eddy-water-bottle-25oz-fBbJQZ55nAGMKG7ZuhWFAQJUKy55WaGD.jpg",
"image" { "url": "https://media.covver.io/image/camelbak-eddy-water-bottle-25oz-fBbJQZ55nAGMKG7ZuhWFAQJUKy55WaGD.jpg" },
"productId": "bd0fdfce-47e1-4638-a452-1bdc4998cb7c",
"productTitle": "CamelBak Eddy 25oz Bottle Tritan",
"variantId": "b3415cca-24e2-4c88-847b-de78c9e78ae9"
"variantTitle": "Clear / Large",
}
]
}
```
## Note
This is not guaranteed to include all orderLineItems of the order. This webhook depends on our vendors and when they confirm the order.
# Order fulfilled webhook event
Source: https://docs.covver.io/api-reference/webhooks/order-fulfilled
Webhook data sent when the order is sent to the shipping company
## Webhook data
```ts theme={null}
type OrderFulfilledData {
id: string;
createdAt: string;
orderNumber: string;
externalId?: string;
orderLineItems: {
id: string;
title: string;
price: number;
quantity: number;
// @deprecated, please use image.url
imageUrl: string,
image: { url: string; },
productId: string;
productTitle: string;
variantId: string;
variantTitle: string;
personalizations?: Partial
sha?: string;
}[],
shipment: {
carrier: string;
trackingUrl: string;
trackingNumber: string
orderLineItems: {id: string}[]
}
}
```
## Example Webhook data without personalizations
```ts theme={null}
{
"id": "9a862a01-5e27-4961-ac1c-643de3ac07db",
"createdAt": "2024-01-01 15:45:25.932562",
"orderNumber": "123",
"orderLineItems": [
{
"id": "4251d65d-fab8-46de-908b-204c02ee32f0",
"title": "CamelBak Eddy 25oz Bottle Tritan - Clear / Large",
"price": 54,
"quantity": 1,
// @deprecated, please use image.url
"imageUrl": "https://media.covver.io/image/camelbak-eddy-water-bottle-25oz-fBbJQZ55nAGMKG7ZuhWFAQJUKy55WaGD.jpg",
"image" { "url": "https://media.covver.io/image/camelbak-eddy-water-bottle-25oz-fBbJQZ55nAGMKG7ZuhWFAQJUKy55WaGD.jpg" }, "productId": "bd0fdfce-47e1-4638-a452-1bdc4998cb7c",
"productId": "bd0fdfce-47e1-4638-a452-1bdc4998cb7c",
"productTitle": "CamelBak Eddy 25oz Bottle Tritan",
"variantId": "b3415cca-24e2-4c88-847b-de78c9e78ae9"
"variantTitle": "Clear / Large",
}
],
"shipment": {
"carrier": "FedEx",
"trackingUrl": "https://www.fedex.com/fedextrack/?trknbr=123456789",
"trackingNumber": "123456789"
}
}
```
## Note
This is not guaranteed to include all orderLineItems of the order. Items may be packaged and shipped separately.
# Order placed webhook event
Source: https://docs.covver.io/api-reference/webhooks/order-placed
Webhook data sent for order placed events
## Webhook data
```ts theme={null}
type OrderPlacedData {
id: string;
createdAt: string;
orderNumber: string;
externalId?: string;
orderLineItems: {
id: string;
title: string;
price: number;
quantity: number;
// @deprecated, please use image.url
imageUrl: string,
image: { url: string; },
productId: string;
productTitle: string;
variantId: string;
variantTitle: string;
personalizations?: Partial
sha?: string;
}[]
}
```
## Example Webhook data without personalizations
```ts theme={null}
{
"id": "9a862a01-5e27-4961-ac1c-643de3ac07db",
"createdAt": "2024-01-01 15:45:25.932562",
"orderNumber": "123",
"orderLineItems": [
{
"id": "4251d65d-fab8-46de-908b-204c02ee32f0",
"title": "CamelBak Eddy 25oz Bottle Tritan - Clear / Large",
"price": 54,
"quantity": 1,
// @deprecated, please use image.url
"imageUrl": "https://media.covver.io/image/camelbak-eddy-water-bottle-25oz-fBbJQZ55nAGMKG7ZuhWFAQJUKy55WaGD.jpg",
"image" { "url": "https://media.covver.io/image/camelbak-eddy-water-bottle-25oz-fBbJQZ55nAGMKG7ZuhWFAQJUKy55WaGD.jpg" },
"productId": "bd0fdfce-47e1-4638-a452-1bdc4998cb7c",
"productTitle": "CamelBak Eddy 25oz Bottle Tritan",
"variantId": "b3415cca-24e2-4c88-847b-de78c9e78ae9"
"variantTitle": "Clear / Large",
}
{
"id": "72137631-b158-4957-b89d-06f72f3d13f8",
"title": "Round Wireless Charger - White / 10cm",
"price": 67,
"quantity": 1,
// @deprecated, please use image.url
"imageUrl": "https://media.covver.io/image/dcgh-LgCUfTDi1FXCXeDfXKE4HFvSS6gqHtIh.png",
"image" { "url": "https://media.covver.io/image/dcgh-LgCUfTDi1FXCXeDfXKE4HFvSS6gqHtIh.png" },
"productId": "4232f9b8-02e9-46f8-9feb-020c2293d5b8",
"productTitle": "Round Wireless Charger",
"variantId": "c8d29c2c-5626-4795-80cf-7aa2ba9137c8"
"variantTitle": " White / 10cm",
}
]
}
```
## Note
This will include all orderLineItems
# Product created webhook event
Source: https://docs.covver.io/api-reference/webhooks/product-created
Webhook data sent when a new product is created
## Webhook data
```ts theme={null}
type ProductCreatedData {
id: string;
title: string;
slug: string;
model: string | null;
brand: string | null;
description: string;
isInStock: boolean;
isDiscontinued: boolean;
priceRange: { minVariantPrice: number; maxVariantPrice: number };
retailPriceRange?: { minVariantPrice: number; maxVariantPrice: number };
options: {
name: 'size' | 'color';
values: { title: string; colorCode?: string; colorCode2?: string }[];
}[];
variants: {
id: string;
images: { url: string; lowResUrl: string; width: number; height: number }[];
isAvailableForSale: boolean;
options: {
name: 'size' | 'color';
value: { title: string; colorCode?: string; colorCode2?: string };
}[];
price: number;
retailPrice?: number;
title: string;
}[];
featuredImage: {
url: string;
lowResUrl: string;
width: number;
height: number;
};
};
```
## Example Webhook data
```ts theme={null}
{
"id": "68a44ab2-6e2f-4474-9dc8-b0033638c7dc",
"title": "Men's Champion Sweatshirt",
"slug": "mens-champion-sweatshirt",
"model": "Sweatshirt",
"brand": "Champion",
"description": "A cool sweatshirt",
"isInStock": true,
"isDiscontinued": false,
"priceRange": {
"minVariantPrice": 10,
"maxVariantPrice": 11
},
"priceMarkup": {
"type": "FlatPercent",
"value": 5
},
"options": [
{
"name": "size",
"values": [
{
"title": "L"
},
{
"title": "M"
}
]
},
{
"name": "color",
"values": [
{
"title": "White",
"colorCode": "#FFFFFF"
},
{
"title": "Black",
"colorCode": "#000000"
}
]
}
],
"variants": [
{
"id": "002196d0-fecd-4633-94d6-abd3675bdb2d",
images: [
{
"width": 1000,
"height": 1000,
"url": "https://media.covver.io/mockups/eabce69f-daa7-45b3-a7bf-f374fac95efd.jpeg",
"lowResUrl": "https://media.covver.io/mockups/eabce69f-daa7-45b3-a7bf-f374fac95efd.jpeg"
}
],
"isAvailableForSale": true,
"options": [
{
"name": "size",
"value": {
"title": "L"
}
},
{
"name": "color",
"value": {
"title": "Black",
"colorCode": "#000000"
}
}
],
"price": 10,
"title": "Black"
}
],
"featuredImage": {
"width": 1000,
"height": 1000,
"url": "https://media.covver.io/mockups/eabce69f-daa7-45b3-a7bf-f374fac95efd.jpeg",
"lowResUrl": "https://media.covver.io/mockups/eabce69f-daa7-45b3-a7bf-f374fac95efd.jpeg"
}
}
```
## Note
This does not trigger when a new collection is created with all of the new products. This is only triggered when new products are added to a collection
# Product hidden webhook event
Source: https://docs.covver.io/api-reference/webhooks/product-hidden
Webhook data sent when a product is hidden from a store
## Webhook data
```ts theme={null}
type ProductHiddenData {
id: string;
title: string;
slug: string;
model: string | null;
brand: string | null;
description: string;
isInStock: boolean;
isDiscontinued: boolean;
priceRange: { minVariantPrice: number; maxVariantPrice: number };
retailPriceRange?: { minVariantPrice: number; maxVariantPrice: number };
options: {
name: 'size' | 'color';
values: { title: string; colorCode?: string; colorCode2?: string }[];
}[];
variants: {
id: string;
images: { url: string; lowResUrl: string; width: number; height: number }[];
isAvailableForSale: boolean;
options: {
name: 'size' | 'color';
value: { title: string; colorCode?: string; colorCode2?: string };
}[];
price: number;
retailPrice?: number;
title: string;
}[];
featuredImage: {
url: string;
lowResUrl: string;
width: number;
height: number;
};
hiddenAt: string;
};
```
## Example Webhook data
```ts theme={null}
{
"id": "68a44ab2-6e2f-4474-9dc8-b0033638c7dc",
"title": "Men's Champion Sweatshirt",
"slug": "mens-champion-sweatshirt",
"model": "Sweatshirt",
"brand": "Champion",
"description": "A cool sweatshirt",
"isInStock": true,
"isDiscontinued": false,
"priceRange": {
"minVariantPrice": 10,
"maxVariantPrice": 11
},
"priceMarkup": {
"type": "FlatPercent",
"value": 5
},
"options": [
{
"name": "size",
"values": [
{
"title": "L"
},
{
"title": "M"
}
]
},
{
"name": "color",
"values": [
{
"title": "White",
"colorCode": "#FFFFFF"
},
{
"title": "Black",
"colorCode": "#000000"
}
]
}
],
"variants": [
{
"id": "002196d0-fecd-4633-94d6-abd3675bdb2d",
images: [
{
"width": 1000,
"height": 1000,
"url": "https://media.covver.io/mockups/eabce69f-daa7-45b3-a7bf-f374fac95efd.jpeg",
"lowResUrl": "https://media.covver.io/mockups/eabce69f-daa7-45b3-a7bf-f374fac95efd.jpeg"
}
],
"isAvailableForSale": true,
"options": [
{
"name": "size",
"value": {
"title": "L"
}
},
{
"name": "color",
"value": {
"title": "Black",
"colorCode": "#000000"
}
}
],
"price": 10,
"title": "Black"
}
],
"featuredImage": {
"width": 1000,
"height": 1000,
"url": "https://media.covver.io/mockups/eabce69f-daa7-45b3-a7bf-f374fac95efd.jpeg",
"lowResUrl": "https://media.covver.io/mockups/eabce69f-daa7-45b3-a7bf-f374fac95efd.jpeg"
},
"hiddenAt": "2024-02-22 07:41:07.905256"
}
```
# Product shown webhook event
Source: https://docs.covver.io/api-reference/webhooks/product-shown
Webhook data sent when a product is added back to a store
## Webhook data
```ts theme={null}
type ProductShownData {
id: string;
title: string;
slug: string;
model: string | null;
brand: string | null;
description: string;
isInStock: boolean;
isDiscontinued: boolean;
priceRange: { minVariantPrice: number; maxVariantPrice: number };
retailPriceRange?: { minVariantPrice: number; maxVariantPrice: number };
options: {
name: 'size' | 'color';
values: { title: string; colorCode?: string; colorCode2?: string }[];
}[];
variants: {
id: string;
images: { url: string; lowResUrl: string; width: number; height: number }[];
isAvailableForSale: boolean;
options: {
name: 'size' | 'color';
value: { title: string; colorCode?: string; colorCode2?: string };
}[];
price: number;
retailPrice?: number;
title: string;
}[];
featuredImage: {
url: string;
lowResUrl: string;
width: number;
height: number;
};
};
```
## Example Webhook data
```ts theme={null}
{
"id": "68a44ab2-6e2f-4474-9dc8-b0033638c7dc",
"title": "Men's Champion Sweatshirt",
"slug": "mens-champion-sweatshirt",
"model": "Sweatshirt",
"brand": "Champion",
"description": "A cool sweatshirt",
"isInStock": true,
"isDiscontinued": false,
"priceRange": {
"minVariantPrice": 10,
"maxVariantPrice": 11
},
"priceMarkup": {
"type": "FlatPercent",
"value": 5
},
"options": [
{
"name": "size",
"values": [
{
"title": "L"
},
{
"title": "M"
}
]
},
{
"name": "color",
"values": [
{
"title": "White",
"colorCode": "#FFFFFF"
},
{
"title": "Black",
"colorCode": "#000000"
}
]
}
],
"variants": [
{
"id": "002196d0-fecd-4633-94d6-abd3675bdb2d",
images: [
{
"width": 1000,
"height": 1000,
"url": "https://media.covver.io/mockups/eabce69f-daa7-45b3-a7bf-f374fac95efd.jpeg",
"lowResUrl": "https://media.covver.io/mockups/eabce69f-daa7-45b3-a7bf-f374fac95efd.jpeg"
}
],
"isAvailableForSale": true,
"options": [
{
"name": "size",
"value": {
"title": "L"
}
},
{
"name": "color",
"value": {
"title": "Black",
"colorCode": "#000000"
}
}
],
"price": 10,
"title": "Black"
}
],
"featuredImage": {
"width": 1000,
"height": 1000,
"url": "https://media.covver.io/mockups/eabce69f-daa7-45b3-a7bf-f374fac95efd.jpeg",
"lowResUrl": "https://media.covver.io/mockups/eabce69f-daa7-45b3-a7bf-f374fac95efd.jpeg"
}
}
```
# Product updated webhook event
Source: https://docs.covver.io/api-reference/webhooks/product-updated
Webhook data sent when a product is updated
## Webhook data
```ts theme={null}
type ProductUpdatedData {
id: string;
title: string;
slug: string;
model: string | null;
brand: string | null;
description: string;
isInStock: boolean;
isDiscontinued: boolean;
priceRange: { minVariantPrice: number; maxVariantPrice: number };
retailPriceRange?: { minVariantPrice: number; maxVariantPrice: number };
options: {
name: 'size' | 'color';
values: { title: string; colorCode?: string; colorCode2?: string }[];
}[];
variants: {
id: string;
images: { url: string; lowResUrl: string; width: number; height: number }[];
isAvailableForSale: boolean;
options: {
name: 'size' | 'color';
value: { title: string; colorCode?: string; colorCode2?: string };
}[];
price: number;
retailPrice?: number;
title: string;
}[];
featuredImage: {
url: string;
lowResUrl: string;
width: number;
height: number;
};
};
```
## Example Webhook data
```ts theme={null}
{
"id": "68a44ab2-6e2f-4474-9dc8-b0033638c7dc",
"title": "Men's Champion Sweatshirt",
"slug": "mens-champion-sweatshirt",
"model": "Sweatshirt",
"brand": "Champion",
"description": "A cool sweatshirt",
"isInStock": true,
"isDiscontinued": false,
"priceRange": {
"minVariantPrice": 10,
"maxVariantPrice": 11
},
"priceMarkup": {
"type": "FlatPercent",
"value": 5
},
"options": [
{
"name": "size",
"values": [
{
"title": "L"
},
{
"title": "M"
}
]
},
{
"name": "color",
"values": [
{
"title": "White",
"colorCode": "#FFFFFF"
},
{
"title": "Black",
"colorCode": "#000000"
}
]
}
],
"variants": [
{
"id": "002196d0-fecd-4633-94d6-abd3675bdb2d",
images: [
{
"width": 1000,
"height": 1000,
"url": "https://media.covver.io/mockups/eabce69f-daa7-45b3-a7bf-f374fac95efd.jpeg",
"lowResUrl": "https://media.covver.io/mockups/eabce69f-daa7-45b3-a7bf-f374fac95efd.jpeg"
}
],
"isAvailableForSale": true,
"options": [
{
"name": "size",
"value": {
"title": "L"
}
},
{
"name": "color",
"value": {
"title": "Black",
"colorCode": "#000000"
}
}
],
"price": 10,
"title": "Black"
}
],
"featuredImage": {
"width": 1000,
"height": 1000,
"url": "https://media.covver.io/mockups/eabce69f-daa7-45b3-a7bf-f374fac95efd.jpeg",
"lowResUrl": "https://media.covver.io/mockups/eabce69f-daa7-45b3-a7bf-f374fac95efd.jpeg"
}
}
```
## Note
For now only options and featuredImage are editable via the design editor in the UI
# Trigger webhook
Source: https://docs.covver.io/api-reference/webhooks/trigger-webhook
post /api/ext/v1/backdoor/webhook
Backdoor for testing webhooks
This only works in our development environment
# Update webhook
Source: https://docs.covver.io/api-reference/webhooks/update-webhook
put /api/ext/v1/webhook/{id}
Update a webhook
# Getting Started
Source: https://docs.covver.io/getting-started
Covver's API gives you full power to create engaging experiences, branded and personalized gifts, and custom gifting workflows
![Hero Light]()
![Hero Dark]()
## MCP
Run this to get Covver's docs inside your code editor MCP configuration:
`npx mint-mcp add covver`
## Environments
* Staging - `https://staging-api.covver.io`
* Production - `https://api.covver.io`
## Rate limit
There are no rate limits at the moment
## Explore the API
Authenticate your app with the Covver API
Query to get collections, products variants and images to display in your own eCommerce experience
Place orders and query order status
Create an entire branded store for your customers using a simple API, and benefit from our advanced computer vision algorithms
Manage people with access to the store, and manage their credits or gifts budget
# Personalization
Source: https://docs.covver.io/guides/personalization
Personalization follows the regular integration endpoints and allows you to add the end user's details:
To personalize the collection for each end user, add the user's details to the [list products API](/api-reference/catalog/list-a-collection-products). Poll this API until `status !== 'Pending'`
Query the [get product API](/api-reference/catalog/get-product) using the same personalized fields to get all the personalized images
Include the user's details in the `fields` per line item when calling the [place order API](/api-reference/orders/place-order)
You can use the [collection status API](/api-reference/catalog/get-collection-status) to get the status of a personalized collection
## Personalized designs
A personalized design allows injecting data fields into the design automatically, and at scale.
To setup a collection with personalized designs, please contact your customer success manager or dev support.
The following fields can be used in personalized designs out-of-the-box:
* name (first name, last name, initials)
* birthdate (full date, age, birth year, zodiac sign, elapsed)
* start date (full date, start year, years of service)
* location (city/country/site)
* department
Our design team can help customize a collection for specific celebrations like work anniversaries, birthdays, onboarding, company events and more
To add more customized fields specific for your platform, please be in touch with our dev support.
You can use the standard [list products API](/api-reference/catalog/list-a-collection-products) to get the list of unpersonalized items for demo purposes