` as the forwarding address
5. Finally, click "Create filter"
***
## Step 3: Link Cash App to SellApp [#step-3-link-cash-app-to-sellapp]
The second step is to add your Cash App details to your SellApp storefront:
1. Navigate to [your storefront payment settings by clicking here](https://sell.app/dashboard/settings?settings=payment).
2. Click Cash App. In the modal that appears, follow the steps. Make sure you enter **the email address you added to your Cash App in step 1**
3. Save the settings. If all details were entered correctly, you'll now see Cash App as "Active" in the payment settings.
All done! Cash App has been enabled for your store and you can now enable Cash App for every new product you create.
***
## Optionally: Enabling Cash App for products which already exist [#optionally-enabling-cash-app-for-products-which-already-exist]
If you want to enable Cash App for products which already exist, here's how to do so:
1. Navigate to [your products dashboard by clicking here](https://sell.app/dashboard/listings).
2. On the products page, toggle the checkboxes of the products you want to enable Cash App for.
3. Click the "Update Payment Methods" button found in the "bulk update" dropdown that appears.
* A modal will pop up; check Cash App *(& optionally other payment methods you'd like enabled)*
4. Finally, click "Update All" in the modal to update the products' payment methods.
That's all done for you: all the products you selected will now have Cash App enabled as a payment method, which customers will be able to select when making a purchase.
# Crypto (/docs/crypto)
Payments in crypto are becoming more and more prevalent, especially so for digital goods.
We've made it possible to directly link your crypto wallets to your SellApp storefront, helping you **earn crypto that directly gets deposited to your linked wallets**. No hold periods, no extra transaction fees, and no withdrawal fees.
***
## Linking Wallets [#linking-wallets]
1. Navigate to [your storefront payment settings by clicking here](https://sell.app/dashboard/settings?settings=payment).
2. You will find a "Cryptocurrencies" section. Click on the relevant cryptocurrency you'd like to link to display a setup modal.
3. Enter your wallet address or XPUB key
1. If you are linking Litecoin or Bitcoin, you need to get an XPUB. Don't know how to do so? [Navigate to the support article by clicking here](#support-how-to-find-extended-public-key-xpub-for-bitcoin-and-or-litecoin)
* The xpub does not necessarily start with "xpub...", it can also start with "zpub..." or "ypub...". If that's the case, just copy/paste the relevant value from your wallet to the modal and save. It will work without an issue.
2. If you are linking Monero, it requires a Monero address to be entered, as well as your wallet's "Private View Key"
3. If you are linking any of the other wallets, just copy/paste your wallet address and you'll be good to go
4. Finally, click "Save" in the modal
That's it! Your crypto wallet has now been enabled for your store, you can enable it as a payment method for every new product you create.
***
## Optionally: Enabling crypto for products which already exist [#optionally-enabling-crypto-for-products-which-already-exist]
If you want to enable crypto for products which already exist, here's how to do so:
1. Navigate to [your products dashboard by clicking here](https://sell.app/dashboard/listings).
2. On the products page, toggle the checkboxes of the products you want to enable crypto for.
3. Click the "Update Payment Methods" button found in the "bulk update" dropdown that appears.
* A modal will pop up; check the relevant crypto option *(, as well as all other payment methods you'd like enabled)*
4. Finally, click "Update All" in the modal to update the products' payment methods.
That's all done for you: all the products you selected will now have crypto enabled as a payment method, which customers will be able to select when making a purchase.
***
## Support: How to find Extended Public Key *(XPUB)* for Bitcoin and/or Litecoin [#support-how-to-find-extended-public-key-xpub-for-bitcoin-andor-litecoin]
For certain crypto, SellApp generates new payment addresses for every order created. These addresses are generated via the extended public key (xpub/zpub/ypub) that you link to your store.
The benefits of linking an XPUB to your SellApp store:
1. SellApp does not require access to your private keys, meaning there is zero risk of something going wrong.
2. Bitcoin/Litecoin payments go directly to your wallet, we don't hold funds or charge double the transaction fees.
3. Enhanced privacy as every new order created generates a fresh address
We **strongly** recommend using either Exodus or Electrum. **Other wallets, such as Ledger, are known to cause issues** and **may result in funds not being accessible** unless you're technical
**Where to find xpub in Exodus:**
When exporting your XPUB from Exodus for Bitcoin, **make sure to use the second XPUB in the list, which starts with a ZPUB**
1. Open your Exodus desktop wallet app *(Note, the mobile wallet does not have this option)*
2. Navigate to the Bitcoin or Litecoin wallet in the app
3. Click the three dots at the top right, then select "Export XPUB" to download your xpub/zpub/ypub key.
4. Copy the xpub/zpub/ypub key from the exported file and paste it [into your SellApp Bitcoin/Litecoin wallet settings](https://sell.app/dashboard/settings?settings=payment)
* **Copy and paste the second option for Bitcoin, which starts with a ZPUB**
**Where to find xpub in Electrum Wallet:**
1. Open your Electrum app.
2. Navigate to "Wallet" -> "Information".
3. A modal will appear. The second text area should be titled as "Master Public Key". In the text area itself, it should show your public key that starts with "xpub", "zpub", or "ypub"
4. Copy the xpub/zpub/ypub key and paste it [into your SellApp Bitcoin/Litecoin wallet settings](https://sell.app/dashboard/settings?settings=payment)
**Where to find xpub in Coinbase, Binance, Trust Wallet, Kraken, etc.:**
These providers hold funds on your behalf, so you don't have an actual wallet with them. This means that you can't retrieve an "xpub", "zpub", or "ypub" key from them.
If this is the case, we'd recommend downloading [Electrum](https://electrum.org) or [Exodus](https://exodus.com/) to use as your SellApp wallet.
***
## Support: I didn't receive the funds in my wallet [#support-i-didnt-receive-the-funds-in-my-wallet]
There are two possible reasons why you don't see the funds you've received:
1. You manually marked an order as completed. **orders should never be marked as completed unless you're absolutely certain you've received the funds**
2. You copy/pasted an XPUB from a wallet other than Electrum/Exodus
In the first case, this is an user error as funds might never have been sent by the customer. We cannot assist in this scenario, as the payment very likely does not exist.
In the second case, you will want to export your seed and import it into [Electrum](https://electrum.org). Then, you'd need to scan the derivations and/or set the derivation path manually.
To see what derivation path your funds are in, we suggest using the following Trezor link: [https://btc1.trezor.io/xpub/EnterYourXpubHere](https://btc1.trezor.io/xpub/EnterYourXpubHere)
The above link will show all of the payments your XPUB has received, and the derivation path for each address.
# Paddle (/docs/paddle)
SellApp makes it very easy to link your [Paddle](https://paddle.com/) account and start accepting PayPal, credit/debit card, and other payment types for your digital products. Here's how.
***
## Adding our webhook [#adding-our-webhook]
First, we need to add the SellApp webhook endpoint to your Paddle account. **Without it added, payments will not automatically process.** Here's how to do so:
1. Go to your Paddle events settings, [you can do so by clicking here](https://vendors.paddle.com/alerts-webhooks).
2. Enter `https://sell.app/paddle/webhook` in the "webhook URL" input, found in the `URLs for receiving webhooks` section.
* *Note: Don't visit this URL directly, it will display an error page. Just copy/paste the URL in the modal and you're good to go.*
3. Scroll down to the "One-off purchases" section, and toggle on all events: `Payment Success`, `Payment Refunded`, `Order Processing Completed` *(the webhook option on the right, not the email one)*.
Without the above webhook URL added and events toggled on, SellApp cannot detect or process Paddle payments automatically, so make sure to add it first.
***
## Linking Paddle [#linking-paddle]
Now that the webhook endpoint has been added and events have been enabled, we can start linking Paddle to your SellApp storefront. Here's how to do so:
1. Navigate to [your storefront payment settings by clicking here](https://sell.app/dashboard/settings?settings=payment).
2. You will find a "Paddle" button. click it to open the modal which displays **three** input fields: "**Vendor ID**", "**Vendor Auth Code**", "**Public key**".
1. [You can find your Vendor ID and Vendor Auth Code by clicking here](https://vendors.paddle.com/authentication).
1. If you don't have an auth code, you can click "Generate Key" to generate a new auth code
2. Click "Reveal auth code" to display your auth code, copy the value and paste it into our "Vendor Auth Code" input
3. At the top of the page you will find "Your Paddle Vendor ID". Copy and past the ID into our "Vendor ID" input
2. [You can find your public key by clicking here](https://vendors.paddle.com/public-key).
1. Copy the value displayed on Paddle's page *(The entire thing, from "BEGIN PUBLIC KEY, to END PUBLIC KEY")*
2. Paste it into our "Public key" input
3. Save the settings by clicking "Save" in the SellApp modal
That's it! Paddle has been enabled for your store and you can now enable Paddle for every new product you create.
***
## Optionally: Enabling Paddle for products which already exist [#optionally-enabling-paddle-for-products-which-already-exist]
If you want to enable Paddle for products which already exist, here's how to do so:
1. Navigate to [your products dashboard by clicking here](https://sell.app/dashboard/listings).
2. On the products page, toggle the checkboxes of the products you want to enable Paddle for.
3. Click the "Update Payment Methods" button found in the "bulk update" dropdown that appears.
* A modal will pop up; check Paddle *(& optionally other payment methods you'd like enabled)*
4. Finally, click "Update All" in the modal to update the products' payment methods.
That's all done for you: all the products you selected will now have Paddle enabled as a payment method, which customers will be able to select when making a purchase.
# Introduction (/docs/payment-methods-introduction)
Wondering where and how you can add/remove payment methods, or have payment-related questions? This page will help you.
***
## Where can I add or remove a payment method? [#where-can-i-add-or-remove-a-payment-method]
You can add/remove payment methods in your SellApp storefront's payment settings.
If you don't know where that is, [here's a link to your storefront's payment settings](https://sell.app/dashboard/settings?settings=payment).
***
### How do I add or remove a payment method? [#how-do-i-add-or-remove-a-payment-method]
Each payment method has its own setup flow. Start with the method you want to enable:
Accept credit and debit card payments through Authorize.net.
Configure Cash App and email forwarding so payments process automatically.
Link wallets and XPUBs for supported cryptocurrency payments.
Connect Paddle and register the SellApp webhook endpoint.
Link PayPal directly or enable it with your PayPal email address.
Add your Square access token and location ID.
Complete Stripe onboarding and enable it for your products.
***
## How do I enable or disable a payment method for all of my products? [#how-do-i-enable-or-disable-a-payment-method-for-all-of-my-products]
There are two ways to enable or disable a payment method for all products at once:
1. Via the [storefront payment settings](https://sell.app/dashboard/settings?settings=payment):
1. To enable: When adding a payment method, in the payment method's popup modal, toggle "Enable X *(where X is the payment method)* for all existing products?" on before clicking save.
2. To disable: Remove the payment method by emptying the respective modal's input and saving. Once done, the payment method should say "Not configured" which in turn will have disabled it for all existing products that had the payment method enabled.
2. Via [your product dashboard](https://sell.app/dashboard/listings)
1. Click the checkbox for the products on the left hand side
2. Click "Select all" if you'd like to apply this change to all existing products in your storefront
3. Select the "Bulk Update" dropdown and then click "Update Payment Methods"
4. Toggle the payment methods you would like to accept on *(or keep the one you don't want to accept unchecked)*
5. Once you click "Update All", all of the selected products will be updated to only the ones you've toggled on in step 4.
***
## How do I get my earnings? [#how-do-i-get-my-earnings]
SellApp does not hold your money or makes you wait until a specific payout date for your earned funds.
The customer does not pay our account, but instead the money is immediately sent from them to your linked payment processor account.
This means that whenever a sale is made, you instantly get access to the funds.
# PayPal (/docs/paypal)
SellApp makes it very easy to link your [PayPal](https://www.paypal.com/) account and start accepting PayPal payments for your digital products. Here's how.
***
## Linking PayPal [#linking-paypal]
1. Navigate to [your storefront payment settings by clicking here](https://sell.app/dashboard/settings?settings=payment).
2. You will find a "PayPal" button. Click it, a modal will appear displaying a "**Connect with PayPal button**". When you click it, you will be redirected to PayPal and asked if you want to give SellApp the respective permissions.
3. When you are redirected back to SellApp, your PayPal account will have successfully been linked with your store.
4. *Optional:* If you don't want to to link your PayPal account directly, you can also simply enter your PayPal email address in step 2 and click "Save"
That's it! PayPal has been enabled for your store and you can now enable PayPal for every new product you create.
***
## Optionally: Enabling PayPal for products which already exist [#optionally-enabling-paypal-for-products-which-already-exist]
If you want to enable PayPal for products which already exist, here's how to do so:
1. Navigate to [your products dashboard by clicking here](https://sell.app/dashboard/listings).
2. On the products page, toggle the checkboxes of the products you want to enable PayPal for.
3. Click the "Update Payment Methods" button found in the "bulk update" dropdown that appears.
* A modal will pop up; check PayPal *(& optionally other payment methods you'd like enabled)*
4. Finally, click "Update All" in the modal to update the products' payment methods.
That's all done for you: all the products you selected will now have PayPal enabled as a payment method, which customers will be able to select when making a purchase.
***
## Support: Pending PayPal payments [#support-pending-paypal-payments]
There's two types of pending PayPal payment types:
1. A pending payment where you have to accept the money on your account before the order can get processed
1. This is due to your PayPal account not having the respective balance enabled which the customer paid with.
* For example: if you live in the EU and only have an Euro balance enabled on your account, but then sign up to SellApp and list a product in USD, the money will be sent as USD
* Since PayPal does not know whether you want to reject the payment, or whether you'd like to convert the USD earnings into Euro, or whether you'd like to open a separate USD balance, this payment will be set as pending until you decide
2. The solution here is to either open a USD balance *(it's free to open as many balances on PayPal as you'd like)*, or price your product in a currency your PayPal account has a balance opened for.
* We strongly advise applying the solution as fast as possible, as each and every order made via SellApp will continue to remain stuck and not process until you accept/convert the payment.
2. A pending payment that has been completed on SellApp's side, but the money being held by PayPal for 1/3/7 days
1. This is due to an internal system on PayPal's end.
* If you're a new seller, or a seller who hasn't had activity on PayPal in a long time, they may temporarily place you into this system.
* We at SellApp can't influence anything on this end, it's a seemingly arbitrary decision applied by PayPal
2. The solution here is to wait it out. After a handful of successful sales with no disputes, PayPal will move you out of their system and you'll be able to accept payments instantly.
# Square (/docs/square)
SellApp makes it very easy to link your [Square](https://square.com/) account and start accepting PayPal, credit/debit card, and other payment types for your digital products. Here's how.
***
## Linking Square [#linking-square]
Here's how to link Square to your SellApp account:
1. Navigate to [your storefront payment settings by clicking here](https://sell.app/dashboard/settings?settings=payment).
2. You will find a "Square" button. click it to open the modal which displays **two** input fields: "**Access Token**" and "**Location ID**".
1. [You can find your access token by clicking here](https://developer.squareup.com/apps). If you don't have an app yet, click "Create App" and copy the provided token.
2. [You can find your location ID by clicking here](https://developer.squareup.com/) -> Click your app -> locations and copy the provided location ID.
3. Paste the above values in the respective inputs and save the settings by clicking "Save" in the SellApp modal
That's it! Square has been enabled for your store and you can now enable Square for every new product you create.
***
## Optionally: Enabling Square for products which already exist [#optionally-enabling-square-for-products-which-already-exist]
If you want to enable Square for products which already exist, here's how to do so:
1. Navigate to [your products dashboard by clicking here](https://sell.app/dashboard/listings).
2. On the products page, toggle the checkboxes of the products you want to enable Square for.
3. Click the "Update Payment Methods" button found in the "bulk update" dropdown that appears.
* A modal will pop up; check Square *(& optionally other payment methods you'd like enabled)*
4. Finally, click "Update All" in the modal to update the products' payment methods.
That's all done for you: all the products you selected will now have Square enabled as a payment method, which customers will be able to select when making a purchase.
# Stripe (/docs/stripe)
SellApp makes it very easy to link your [Stripe](https://stripe.com/) account and start accepting card payments for your digital products. Here's how.
Once Stripe is enabled, customers can select a wide variety of payment methods on Stripe's checkout page. These include Apple/Google Pay, iDeal, Bancontact, Sofort, Giropay, and more.
***
## Linking Stripe [#linking-stripe]
1. Navigate to [your storefront payment settings by clicking here](https://sell.app/dashboard/settings?settings=payment).
2. You will find a "Stripe" button. Click it to open the Stripe onboarding modal.
3. Click the "**Connect Stripe**" button to be redirected to Stripe's onboarding page:
1. If you already have a Stripe account, enter your Stripe email and log in.
2. Otherwise, enter your email address and go through the onboarding process.
4. Once you've completed Stripe's onboarding process, you will be redirected back to your storefront's payment settings. Click "Stripe" to open the modal again,
1. It should now say "Onboarding Completed".
2. Finally, click "Enable" in the modal
That's it! Stripe has been enabled for your store and you can now enable Stripe for every new product you create.
***
## Optionally: Enabling Stripe for products which already exist [#optionally-enabling-stripe-for-products-which-already-exist]
If you want to enable Stripe for products which already exist, here's how to do so:
1. Navigate to [your products dashboard by clicking here](https://sell.app/dashboard/listings).
2. On the products page, toggle the checkboxes of the products you want to enable Stripe for.
3. Click the "Update Payment Methods" button found in the "bulk update" dropdown that appears.
* A modal will pop up; check Stripe *(& optionally other payment methods you'd like enabled)*
4. Finally, click "Update All" in the modal to update the products' payment methods.
That's all done for you: all the products you selected will now have Stripe enabled as a payment method, which customers will be able to select when making a purchase.
***
## Support: Linking Stripe if it's already connected to another platform [#support-linking-stripe-if-its-already-connected-to-another-platform]
If your Stripe account has already been connected to another platform, and you want to link it to SellApp, you'll find it's not possible unless you disconnect the other platform's link to your account.
Here's how to do so:
* [Click here for Stripe's official guide](https://support.stripe.com/questions/disconnect-your-stripe-account-from-a-connected-third-party-platform)
1. Navigate [to the "Authorized Applications" page on your Stripe dashboard](https://dashboard.stripe.com/account/applications)
2. Click "revoke access" for the relevant platform that has already been connected to your account
3. Finally, you can now link your Stripe account to SellApp without running into any issues
Happy selling!
# Authentication (/docs/api/authentication)
You'll need to authenticate your requests to access any of the endpoints in the
SellApp API. SellApp currently offers one way to authenticate API requests:
using a secret API key.
## Authentication with a secret API key [#authentication-with-a-secret-api-key]
Authenticating with the SellApp API is done by passing your secret API key in
the request headers.
```bash title="Example request with bearer token"
curl --request GET \
--url 'https://sell.app/api/v1/invoices' \
--header 'Authorization: Bearer {ApiKeyHere}' \
--header 'Content-Type: application/json'
```
## Creating and managing a secret API key [#creating-and-managing-a-secret-api-key]
If you do not already have a secret API key, you can generate one in your [store
developers settings](https://sell.app/dashboard/settings?settings=developers).
Always keep your API key safe and rotate it if you suspect it has been
compromised.
API keys are tied to an account, not a storefront. While you can toggle API
permissions on or off while creating an API key, access to resources still
depends on what permissions your account has on the storefront you are
interacting with.
As the owner of a storefront, you will always have full access to all API
endpoints, provided the relevant permissions were enabled when the key was
created.
If your account is part of a storefront as support staff, you can only access
resources that your account has been given permission to manage. For example, a
support staff account limited to tickets cannot modify products or create groups
through the API.
## Multiple stores [#multiple-stores]
If your account belongs to multiple storefronts, you can pass an `X-STORE`
header to specify which store you want to access. If you do not own any stores
or do not pass the header, the API defaults to the first store you own or
joined.
If you want to access `bob.sell.app`, you would pass the slug `bob` via the
`X-STORE` header:
```bash title="Example request accessing bob.sell.app invoices"
curl --request GET \
--url 'https://sell.app/api/v1/invoices' \
--header 'Authorization: Bearer {ApiKeyHere}' \
--header 'X-STORE: bob' \
--header 'Content-Type: application/json'
```
## Using an SDK [#using-an-sdk]
If you use an SDK, you do not need to manage most of the request setup
yourself. Fetch your API key from your developers settings, then let the client
library handle the authentication headers and request plumbing for you.
For currently known packages and integrations, see [SDKs &
Extensions](/api/sdks).
# Errors (/docs/api/errors)
What happens when something goes wrong while you are interacting with the API?
Mistakes happen, so this guide covers the status codes and error types you may
encounter.
Before reaching out to support with an issue, carefully check your code for
incorrectly typed variables and missing or malformed headers.
You can tell if a request was successful by checking the HTTP status code on the
response. If a response is unsuccessful, use the error type and message to
understand what went wrong and to debug the request.
***
## Status codes [#status-codes]
Here are the status code categories returned by the SellApp API:
A `2xx` status code indicates a successful response.
A `4xx` status code indicates a client error.
A `5xx` status code indicates a server error.
***
## Error types [#error-types]
Whenever a request is unsuccessful, the SellApp API returns an error response
with an error type and message. Use this information to understand what went
wrong and how to fix it.
The list of error codes may grow over time. The following code is currently
documented in the legacy API reference:
This means either the API key passed along is incorrectly formatted, or you
are missing a required header.
# Pagination (/docs/api/pagination)
SellApp API list responses are paginated. By default, responses limit results to
fifteen items. You can increase that limit up to one hundred by adding a
`limit` query parameter to your request.
Whenever an API response returns a list of objects, pagination is supported. Use
the `page` query parameter to browse result pages.
## Example using invoices [#example-using-invoices]
In this example, we request page `10` with a limit of `20` results per
page. The response returns twenty invoices and the `last_page` attribute
tells us we have not yet reached the end of the result set.
The response limit of the API resource you are accessing.
The page number you are attempting to access.
```bash title="Manual pagination using cURL"
curl --request GET \
--url 'https://sell.app/api/v1/invoices?page=10&limit=20' \
--header 'Authorization: Bearer {ApiKeyHere}' \
--header 'Content-Type: application/json'
```
```json title="Paginated response"
{
"data": [
{
"id": "1"
},
{
"id": "2"
},
{
"id": "3"
}
],
"meta": {
"current_page": 10,
"from": 181,
"last_page": 42,
"links": [
// ...
]
}
}
```
# SDKs & Extensions (/docs/api/sdks)
SellApp and its community have created API libraries and extensions to make it
easier to integrate with the platform.
We are working toward releasing official packages and integrations, starting
with a WooCommerce plugin for creating charges. We currently do not offer
official SDKs for every language, but members of the SellApp community have
created a handful of open-source packages that may be useful depending on your
stack.
Community packages listed here are not officially endorsed. They are included
because they are open-source and may be useful for your use case.
## Community SDKs & extensions [#community-sdks--extensions]
The official WooCommerce plugin for SellApp.
A community-maintained Node.js wrapper for the SellApp API.
A community-maintained Python package for interacting with SellApp.
A community-maintained .NET integration for SellApp.
A community-maintained React integration for SellApp storefront flows.
***
## Embedding SellApp products [#embedding-sellapp-products]
SellApp offers an official embed solution that lets you place product purchase
flows directly on your own website. Once embedded, customers can complete
purchases without being redirected to your storefront.
For setup instructions, see the [Embedding products](/embedding-products) guide
in the main help documentation.
# Webhooks (/docs/api/webhooks)
Webhooks let your application react when something happens in SellApp, such as
an order being completed or a support ticket receiving a new message.
## Registering webhooks [#registering-webhooks]
To register a webhook, you need a URL in your application that SellApp can call.
You can configure a new webhook from your storefront developers settings under
[the developers tab](https://sell.app/dashboard/settings?settings=developers).
Add your callback URL, pick the [events](#event-types) you want to listen for,
and save the webhook. Whenever one of those events happens, SellApp will send a
webhook request to your endpoint.
## Consuming webhooks [#consuming-webhooks]
When your app receives a webhook request from SellApp, inspect the `event`
attribute to see what triggered it. The first part of the event type tells you
the payload category, such as an order or product.
```json title="Example webhook payload"
{
"event": "order.completed",
"data": {
"id": 236
},
"store": 1
}
```
In the example above, an order was `completed`, and the payload type is
`order`.
***
## Event types [#event-types]
A CashApp payment is pending.
A new feedback was created.
A new order was created.
An existing order was paid.
A paid order was disputed.
A new product was created.
An existing product was updated.
A product was successfully deleted.
A new ticket message was created.
A new product variant was created.
An existing product variant was updated.
An existing product variant ran out of stock.
```json title="Example payload"
{
"event": "ticket_message.created",
"data": {
"author": "CUSTOMER",
"sender": "mark@meta.com",
"content": "Hey, I'm interested in investing.",
"ticket_id": 1337,
"updated_at": "2022-04-20T13:37:69.000000Z",
"created_at": "2022-04-20T13:37:69.000000Z",
"id": 6969,
"ticket": {
"id": 1337,
"title": "Acquisition",
"status": "OPEN",
"customer": {
"id": "c4e45131-a187-3476-9efd-1fb6fbbf2243",
"email": "mark@meta.com"
},
"reference": {
"id": 87654,
"type": "App\\Models\\Invoice"
},
"created_at": "2022-04-20T13:37:69.000000Z",
"updated_at": "2022-04-20T13:37:69.000000Z",
"store_id": 1,
"read_by": 1,
"archived": 0
}
},
"store": 1
}
```
***
## Security [#security]
To verify that a webhook really came from SellApp and not from a malicious
sender, validate the request signature. To create a webhook signing secret,
navigate to your [storefront developers settings](https://sell.app/dashboard/settings?settings=developers),
click **New Secret**, and save it.
Each webhook request contains a `signature` header. You can verify that
signature by hashing the raw request payload with your secret webhook key using
HMAC SHA-256.
JavaScript
Python
PHP
```js
const signature = req.headers['signature'];
const hash = crypto.createHmac('sha256', secret).update(payload).digest('hex');
if (hash === signature) {
// Request has been verified
} else {
// Request could not be verified
}
```
```python
from flask import request
import hashlib
import hmac
signature = request.headers.get("signature")
hash = hmac.new(bytes(secret, "ascii"), bytes(payload, "ascii"), hashlib.sha256)
if hash.hexdigest() == signature:
# Request has been verified
else:
# Request could not be verified
```
```php
$signature = $request['headers']['signature'];
$hash = hash_hmac('sha256', $payload, $secret);
if (hash_equals($hash, $signature)) {
// Request has been verified
} else {
// Request could not be verified
}
```
If your generated signature matches the `signature` header, you can be sure the
request came from SellApp. Keep your secret webhook key safe. If it leaks, you
can no longer trust the signature.
## Discord webhooks and email notifications [#discord-webhooks-and-email-notifications]
Traditional webhook delivery cannot be used to post directly into a Discord
channel. Instead, go to your [store notifications settings](https://sell.app/dashboard/settings?settings=notifications)
and configure your Discord webhook URL there.
Discord and email notification channels support the same types of events as
traditional webhook events. For setup instructions, see the [creating
notifications](/creating-notifications) guide.
# Create a Blacklist Rule (/docs/api/blacklists/create-blacklist)
Create a new blacklist rule for your store.
## Endpoint
- Method: `POST`
- Path: `/v1/blacklists`
- Full URL: `https://sell.app/api/v1/blacklists`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
None.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"required": [
"type",
"data",
"description"
],
"properties": {
"type": {
"type": "string",
"description": "The type of blacklist rule.",
"enum": [
"ASN",
"COUNTRY",
"EMAIL",
"IP",
"WILDCARD_EMAIL"
]
},
"data": {
"type": "string",
"description": "The value to blacklist.",
"example": "@yahoo.com"
},
"description": {
"type": "string",
"description": "Why this rule is being created.",
"example": "This email domain is dangerous"
}
},
"example": {
"type": "WILDCARD_EMAIL",
"data": "@yahoo.com",
"description": "This email domain is dangerous"
}
}
```
Example:
```json
{
"type": "WILDCARD_EMAIL",
"data": "@yahoo.com",
"description": "This email domain is dangerous"
}
```
## Responses
### 200
The newly created blacklist rule.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"description": "A blacklist rule that blocks purchases matching the provided details.",
"required": [
"id",
"type",
"data",
"description",
"created_at",
"updated_at",
"store_id"
],
"properties": {
"id": {
"type": "integer",
"description": "Unique identifier for the blacklist rule.",
"example": 1
},
"type": {
"type": "string",
"description": "The type of blacklist rule.",
"enum": [
"ASN",
"COUNTRY",
"EMAIL",
"IP",
"WILDCARD_EMAIL"
]
},
"data": {
"type": "string",
"description": "The data associated with the rule type, such as an IP address, email, or country code.",
"example": "rick@astley.com"
},
"description": {
"type": "string",
"description": "Why this blacklist rule exists.",
"example": "He rickrolled me too many times."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "When the blacklist rule was created.",
"example": "2022-12-12T12:12:12.000000Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "When the blacklist rule was last updated.",
"example": "2022-12-12T12:12:12.000000Z"
},
"store_id": {
"type": "integer",
"description": "The store ID this blacklist rule belongs to.",
"example": 1
}
}
}
},
"example": {
"data": {
"id": 1,
"type": "WILDCARD_EMAIL",
"data": "@yahoo.com",
"description": "This email domain is dangerous",
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1
}
}
}
```
Example:
```json
{
"data": {
"id": 1,
"type": "WILDCARD_EMAIL",
"data": "@yahoo.com",
"description": "This email domain is dangerous",
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1
}
}
```
### 401
Authentication failed.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Unauthenticated."
}
}
}
```
### 422
The request payload failed validation.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "The given data was invalid."
},
"errors": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"example": {
"data": [
"The data field is required."
]
}
}
}
}
```
# Delete a Blacklist Rule (/docs/api/blacklists/delete-blacklist)
Permanently delete a blacklist rule from your store.
## Endpoint
- Method: `DELETE`
- Path: `/v1/blacklists/{blacklist}`
- Full URL: `https://sell.app/api/v1/blacklists/{blacklist}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `blacklist` (`integer`, required): The unique identifier of the blacklist rule.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
The blacklist rule was deleted successfully.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"description": "A blacklist rule that blocks purchases matching the provided details.",
"required": [
"id",
"type",
"data",
"description",
"created_at",
"updated_at",
"store_id"
],
"properties": {
"id": {
"type": "integer",
"description": "Unique identifier for the blacklist rule.",
"example": 1
},
"type": {
"type": "string",
"description": "The type of blacklist rule.",
"enum": [
"ASN",
"COUNTRY",
"EMAIL",
"IP",
"WILDCARD_EMAIL"
]
},
"data": {
"type": "string",
"description": "The data associated with the rule type, such as an IP address, email, or country code.",
"example": "rick@astley.com"
},
"description": {
"type": "string",
"description": "Why this blacklist rule exists.",
"example": "He rickrolled me too many times."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "When the blacklist rule was created.",
"example": "2022-12-12T12:12:12.000000Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "When the blacklist rule was last updated.",
"example": "2022-12-12T12:12:12.000000Z"
},
"store_id": {
"type": "integer",
"description": "The store ID this blacklist rule belongs to.",
"example": 1
}
}
}
},
"example": {
"data": {
"id": 1,
"type": "WILDCARD_EMAIL",
"data": "@yahoo.com",
"description": "This email domain is dangerous",
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1
}
}
}
```
Example:
```json
{
"data": {
"id": 1,
"type": "WILDCARD_EMAIL",
"data": "@yahoo.com",
"description": "This email domain is dangerous",
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1
}
}
```
### 401
Authentication failed.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Unauthenticated."
}
}
}
```
### 404
The requested blacklist rule was not found.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Blacklist rule not found."
}
}
}
```
# Overview (/docs/api/blacklists)
Blacklist rules help prevent your SellApp storefront from falling victim to
malicious users. They allow you to block fraud attempts by preventing purchases
when customer details match one of your blacklist rules.
This section breaks each blacklist endpoint into its own page so every
operation has a dedicated URL and can be indexed independently.
## Endpoints [#endpoints]
* [List all blacklist rules](/api/blacklists/list-blacklists)
* [Create a blacklist rule](/api/blacklists/create-blacklist)
* [Retrieve a blacklist rule](/api/blacklists/retrieve-blacklist)
* [Update a blacklist rule](/api/blacklists/update-blacklist)
* [Delete a blacklist rule](/api/blacklists/delete-blacklist)
***
## The blacklist model [#the-blacklist-model]
The blacklist model contains the information storefront purchase attempts are
checked against, including the rule type, the rule data, and an internal
description.
### Properties [#properties]
Unique identifier for the blacklist rule.
The type of blacklist rule. Supported types:
* `ASN`
* `COUNTRY`
* `EMAIL`
* `IP`
* `WILDCARD_EMAIL`
The data related to the rule type. Examples:
* `ASN`: `AS1234`
* `COUNTRY`: `BE`
* `EMAIL`: `rick@astley.com`
* `IP`: `1.3.3.7`
* `WILDCARD_EMAIL`: `@yahoo.com`
The description of why this blacklist rule was created.
The time at which this blacklist rule was first created.
The time at which this blacklist rule was last updated.
The ID of the store this blacklist rule belongs to.
# List All Blacklist Rules (/docs/api/blacklists/list-blacklists)
Retrieve a paginated list of blacklist rules.
## Endpoint
- Method: `GET`
- Path: `/v1/blacklists`
- Full URL: `https://sell.app/api/v1/blacklists`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
None.
## Query Parameters
- `limit` (`integer`, optional): Limit the number of blacklist rules returned.
- `page` (`integer`, optional): The page number you are attempting to access.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
A paginated list of blacklist rules.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"required": [
"data",
"links",
"meta"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"description": "A blacklist rule that blocks purchases matching the provided details.",
"required": [
"id",
"type",
"data",
"description",
"created_at",
"updated_at",
"store_id"
],
"properties": {
"id": {
"type": "integer",
"description": "Unique identifier for the blacklist rule.",
"example": 1
},
"type": {
"type": "string",
"description": "The type of blacklist rule.",
"enum": [
"ASN",
"COUNTRY",
"EMAIL",
"IP",
"WILDCARD_EMAIL"
]
},
"data": {
"type": "string",
"description": "The data associated with the rule type, such as an IP address, email, or country code.",
"example": "rick@astley.com"
},
"description": {
"type": "string",
"description": "Why this blacklist rule exists.",
"example": "He rickrolled me too many times."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "When the blacklist rule was created.",
"example": "2022-12-12T12:12:12.000000Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "When the blacklist rule was last updated.",
"example": "2022-12-12T12:12:12.000000Z"
},
"store_id": {
"type": "integer",
"description": "The store ID this blacklist rule belongs to.",
"example": 1
}
}
}
},
"links": {
"type": "object",
"properties": {
"first": {
"type": "string",
"example": "https://sell.app/api/v1/blacklists?page=1"
},
"last": {
"type": "string",
"example": "https://sell.app/api/v1/blacklists?page=4"
},
"prev": {
"type": [
"string",
"null"
],
"example": null
},
"next": {
"type": [
"string",
"null"
],
"example": "https://sell.app/api/v1/blacklists?page=2"
}
}
},
"meta": {
"type": "object",
"properties": {
"current_page": {
"type": "integer",
"example": 1
},
"from": {
"type": "integer",
"example": 1
},
"last_page": {
"type": "integer",
"example": 4
},
"path": {
"type": "string",
"example": "https://sell.app/api/v1/blacklists"
},
"per_page": {
"type": "integer",
"example": 15
},
"to": {
"type": "integer",
"example": 15
},
"total": {
"type": "integer",
"example": 57
}
}
}
},
"example": {
"data": [
{
"id": 1,
"type": "EMAIL",
"data": "rick@astley.com",
"description": "He rickrolled me too many times.",
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1
}
],
"links": {
"first": "https://sell.app/api/v1/blacklists?page=1",
"last": "https://sell.app/api/v1/blacklists?page=4",
"prev": null,
"next": "https://sell.app/api/v1/blacklists?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 4,
"path": "https://sell.app/api/v1/blacklists",
"per_page": 15,
"to": 15,
"total": 57
}
}
}
```
Example:
```json
{
"data": [
{
"id": 1,
"type": "EMAIL",
"data": "rick@astley.com",
"description": "He rickrolled me too many times.",
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1
}
],
"links": {
"first": "https://sell.app/api/v1/blacklists?page=1",
"last": "https://sell.app/api/v1/blacklists?page=4",
"prev": null,
"next": "https://sell.app/api/v1/blacklists?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 4,
"path": "https://sell.app/api/v1/blacklists",
"per_page": 15,
"to": 15,
"total": 57
}
}
```
### 401
Authentication failed.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Unauthenticated."
}
}
}
```
# Retrieve a Blacklist Rule (/docs/api/blacklists/retrieve-blacklist)
Retrieve a specific blacklist rule by its unique identifier.
## Endpoint
- Method: `GET`
- Path: `/v1/blacklists/{blacklist}`
- Full URL: `https://sell.app/api/v1/blacklists/{blacklist}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `blacklist` (`integer`, required): The unique identifier of the blacklist rule.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
The requested blacklist rule.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"description": "A blacklist rule that blocks purchases matching the provided details.",
"required": [
"id",
"type",
"data",
"description",
"created_at",
"updated_at",
"store_id"
],
"properties": {
"id": {
"type": "integer",
"description": "Unique identifier for the blacklist rule.",
"example": 1
},
"type": {
"type": "string",
"description": "The type of blacklist rule.",
"enum": [
"ASN",
"COUNTRY",
"EMAIL",
"IP",
"WILDCARD_EMAIL"
]
},
"data": {
"type": "string",
"description": "The data associated with the rule type, such as an IP address, email, or country code.",
"example": "rick@astley.com"
},
"description": {
"type": "string",
"description": "Why this blacklist rule exists.",
"example": "He rickrolled me too many times."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "When the blacklist rule was created.",
"example": "2022-12-12T12:12:12.000000Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "When the blacklist rule was last updated.",
"example": "2022-12-12T12:12:12.000000Z"
},
"store_id": {
"type": "integer",
"description": "The store ID this blacklist rule belongs to.",
"example": 1
}
}
}
},
"example": {
"data": {
"id": 1,
"type": "WILDCARD_EMAIL",
"data": "@yahoo.com",
"description": "This email domain is dangerous",
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1
}
}
}
```
Example:
```json
{
"data": {
"id": 1,
"type": "WILDCARD_EMAIL",
"data": "@yahoo.com",
"description": "This email domain is dangerous",
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1
}
}
```
### 401
Authentication failed.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Unauthenticated."
}
}
}
```
### 404
The requested blacklist rule was not found.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Blacklist rule not found."
}
}
}
```
# Update a Blacklist Rule (/docs/api/blacklists/update-blacklist)
Update one or more attributes on an existing blacklist rule.
## Endpoint
- Method: `PATCH`
- Path: `/v1/blacklists/{blacklist}`
- Full URL: `https://sell.app/api/v1/blacklists/{blacklist}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `blacklist` (`integer`, required): The unique identifier of the blacklist rule.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"description": "Provide one or more fields to update an existing blacklist rule.",
"properties": {
"type": {
"type": "string",
"description": "The type of blacklist rule.",
"enum": [
"ASN",
"COUNTRY",
"EMAIL",
"IP",
"WILDCARD_EMAIL"
]
},
"data": {
"type": "string",
"description": "The updated value to blacklist.",
"example": "@yahoomail.com"
},
"description": {
"type": "string",
"description": "The updated reason for this rule.",
"example": "This email domain is super dangerous"
}
},
"example": {
"type": "WILDCARD_EMAIL",
"data": "@yahoomail.com",
"description": "This email domain is super dangerous"
}
}
```
Example:
```json
{
"type": "WILDCARD_EMAIL",
"data": "@yahoomail.com",
"description": "This email domain is super dangerous"
}
```
## Responses
### 200
The updated blacklist rule.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "object",
"description": "A blacklist rule that blocks purchases matching the provided details.",
"required": [
"id",
"type",
"data",
"description",
"created_at",
"updated_at",
"store_id"
],
"properties": {
"id": {
"type": "integer",
"description": "Unique identifier for the blacklist rule.",
"example": 1
},
"type": {
"type": "string",
"description": "The type of blacklist rule.",
"enum": [
"ASN",
"COUNTRY",
"EMAIL",
"IP",
"WILDCARD_EMAIL"
]
},
"data": {
"type": "string",
"description": "The data associated with the rule type, such as an IP address, email, or country code.",
"example": "rick@astley.com"
},
"description": {
"type": "string",
"description": "Why this blacklist rule exists.",
"example": "He rickrolled me too many times."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "When the blacklist rule was created.",
"example": "2022-12-12T12:12:12.000000Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "When the blacklist rule was last updated.",
"example": "2022-12-12T12:12:12.000000Z"
},
"store_id": {
"type": "integer",
"description": "The store ID this blacklist rule belongs to.",
"example": 1
}
}
}
},
"example": {
"data": {
"id": 1,
"type": "WILDCARD_EMAIL",
"data": "@yahoo.com",
"description": "This email domain is dangerous",
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1
}
}
}
```
Example:
```json
{
"data": {
"id": 1,
"type": "WILDCARD_EMAIL",
"data": "@yahoo.com",
"description": "This email domain is dangerous",
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1
}
}
```
### 401
Authentication failed.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Unauthenticated."
}
}
}
```
### 404
The requested blacklist rule was not found.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Blacklist rule not found."
}
}
}
```
### 422
The request payload failed validation.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "The given data was invalid."
},
"errors": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"example": {
"data": [
"The data field is required."
]
}
}
}
}
```
# Create a charge (/docs/api/charges/create-a-charge)
This endpoint allows you to create a new charge object. This can be for a paid transaction or a free item claim.
## Endpoint
- Method: `POST`
- Path: `/v2/charges`
- Full URL: `https://sell.app/api/v2/charges`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
None.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email"
},
"return_url": {
"type": "string",
"format": "uri"
},
"cancel_url": {
"type": "string",
"format": "uri"
},
"webhook": {
"type": "string",
"format": "uri"
},
"reference": {
"type": "string"
},
"description": {
"type": "string"
},
"currency": {
"type": "string"
},
"total": {
"type": "integer"
},
"payment_method": {
"type": "string",
"enum": [
"AUTHNET",
"BTCPAY",
"CASHAPP",
"COINBASE",
"PADDLE",
"PAYDASH",
"PAYPAL",
"PAYSTACK",
"SQUARE",
"STRIPE",
"VENMO",
"NMI",
"LIFI",
"BTC",
"LTC",
"ETH",
"XMR",
"SOL",
"ADA",
"BNB",
"TRX",
"MATIC",
"ETH_USDT",
"ETH_USDC",
"ETH_UNI",
"ETH_SHIB",
"ETH_DAI",
"BNB_USDT",
"BNB_USDC",
"TRX_USDT",
"TRX_USDC",
"SOL_USDT",
"SOL_USDC"
]
},
"payment_methods": {
"type": "array",
"items": {
"type": "string",
"enum": [
"AUTHNET",
"BTCPAY",
"CASHAPP",
"COINBASE",
"PADDLE",
"PAYDASH",
"PAYPAL",
"PAYSTACK",
"SQUARE",
"STRIPE",
"VENMO",
"NMI",
"LIFI",
"BTC",
"LTC",
"ETH",
"XMR",
"SOL",
"ADA",
"BNB",
"TRX",
"MATIC",
"ETH_USDT",
"ETH_USDC",
"ETH_UNI",
"ETH_SHIB",
"ETH_DAI",
"BNB_USDT",
"BNB_USDC",
"TRX_USDT",
"TRX_USDC",
"SOL_USDT",
"SOL_USDC"
]
}
},
"use_all_payment_methods": {
"type": "boolean"
},
"deliverable": {
"type": "object",
"additionalProperties": true
},
"metadata": {
"type": "object",
"additionalProperties": true
},
"coupon_code": {
"type": "string"
}
},
"required": [
"email",
"return_url"
]
}
```
Example:
```json
{
"email": "customer@example.com",
"return_url": "https://store.com/thank-you",
"currency": "USD",
"total": 10000,
"payment_method": "PAYPAL",
"reference": "Test Payment"
}
```
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"url": {
"type": "string"
},
"status": {
"type": "string"
}
},
"required": [
"id",
"url",
"status"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 1,
"url": "https://sell.app/store/charges/select/1?signature=...",
"status": "PENDING"
}
}
```
# Overview (/docs/api/charges)
Charges are a slimmed down, more fluid, version of orders. Similar to orders, they are used to take payment for products/services rendered. Unlike orders, however, charges do not manage/handle product delivery.
This makes charges especially useful as a building block for your external project where you handle/manage product delivery manually.
On this page, we'll dive into the different charge endpoints you can use to manage charges programmatically. We'll look at how to view, create, and update charges.
## Endpoints [#endpoints]
* [Create a charge](/api/charges/create-a-charge)
* [Retrieve a charge](/api/charges/retrieve-a-charge)
* [Mark pending charge completed](/api/charges/mark-pending-charge-completed)
* [Mark pending charge voided](/api/charges/mark-pending-charge-voided)
## The charge model [#the-charge-model]
The charge model contains all the information about the charges stores have, including the type, code, and discount amount.
### Properties [#properties]
*(read-only)* The unique identifier for the Charge object.
*(read-only)* The checkout URL you would direct a customer to. The customer can complete the payment or claim the free item on this URL.
*(read-only)* The current status of the charge. Possible values include `PENDING`, `COMPLETED`, `VOIDED`.
The customer's email address. **Required**.
*(optional)* An optional reference for the charge.
*(conditional)* Three-letter ISO currency code. **Required** if `total` > 0.
*(conditional)* The total amount intended to be charged in the smallest currency unit (e.g., cents for USD). **Required** if `currency` is provided and the charge is not free. Must be > 0 for paid charges.
The URL to redirect the customer back to after they complete the checkout process (successfully or not). **Required**.
*(optional)* A URL to send webhook events to for status updates regarding this charge.
*(conditional)* The specific payment gateway(s) for this charge. **Required** for paid charges. You can either pass:
1. One payment method: `"payment_method": "STRIPE"`
2. Multiple payment methods (which the customer can select from): `"payment_methods": ["PAYPAL", "STRIPE"]`
3. All payment methods configured on your SellApp store: `"use_all_payment_methods": true`
*(optional)* A URL to redirect the customer to if they cancel the checkout process.
*(optional)* An optional description for the charge.
*(optional)* A valid SellApp coupon code to apply to the charge.
*(read-only)* Time at which the object was created.
*(read-only)* Time at which the object was last updated.
**Note on Amounts:** All monetary amounts (like `total`) are provided in the smallest currency unit (e.g., cents for USD, pence for GBP).
***
# Mark pending charge completed (/docs/api/charges/mark-pending-charge-completed)
Manually marks a pending charge as completed.
This action should only be performed on charges with a `PENDING` status and where you're certain you've received the funds. Attempting to mark a charge with a different status as completed will result in an error.
## Endpoint
- Method: `PUT`
- Path: `/v2/charges/{charge_id}/completed`
- Full URL: `https://sell.app/api/v2/charges/{charge_id}/completed`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `charge_id` (`integer`, required): The charge id path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
}
```
Example:
```json
{
"message": "Charge Completed Successfully"
}
```
# Mark pending charge voided (/docs/api/charges/mark-pending-charge-voided)
Manually marks a pending charge as voided (canceled).
This action should only be performed on charges with a `PENDING` status. Attempting to void a charge with a different status will result in an error.
## Endpoint
- Method: `PUT`
- Path: `/v2/charges/{charge_id}/voided`
- Full URL: `https://sell.app/api/v2/charges/{charge_id}/voided`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `charge_id` (`integer`, required): The charge id path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
]
}
```
Example:
```json
{
"message": "Charge Voided Successfully"
}
```
# Retrieve a charge (/docs/api/charges/retrieve-a-charge)
Retrieves the details of an existing charge by its ID. Refer to [the charge model](#the-charge-model) section for details on the returned object structure.
## Endpoint
- Method: `GET`
- Path: `/v2/charges/{charge}`
- Full URL: `https://sell.app/api/v2/charges/{charge}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `charge` (`integer`, required): The charge path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"url": {
"type": "string"
},
"status": {
"type": "string"
}
},
"required": [
"id",
"url",
"status"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 1,
"url": "https://sell.app/store/charges/select/1?signature=...",
"status": "PENDING"
}
}
```
# Create a coupon (/docs/api/coupons/create-a-coupon)
This endpoint allows you to create a new coupon. See the code examples for how to create a new coupon with the SellApp API.
## Endpoint
- Method: `POST`
- Path: `/v1/coupons`
- Full URL: `https://sell.app/api/v1/coupons`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
None.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"code": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"PERCENTAGE",
"AMOUNT"
]
},
"discount": {
"type": "number"
},
"store_wide": {
"type": "boolean"
},
"products": {
"type": "array",
"minItems": 1,
"items": {
"type": "integer"
}
},
"limit": {
"type": [
"integer",
"null"
]
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"minimum_amount": {
"type": [
"number",
"null"
]
}
},
"required": [
"code",
"type",
"discount",
"store_wide"
]
}
```
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"code": {
"type": "string"
},
"type": {
"type": "string"
},
"discount": {
"type": "string"
},
"limit": {
"type": "null"
},
"store_wide": {
"type": "boolean"
},
"minimum_amount": {
"type": "null"
},
"expires_at": {
"type": "null"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"deleted_at": {
"type": "null"
}
},
"required": [
"id",
"code",
"type",
"discount",
"limit",
"store_wide",
"minimum_amount",
"expires_at",
"created_at",
"updated_at",
"store_id",
"deleted_at"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 1,
"code": "BONANZA",
"type": "PERCENTAGE",
"discount": "80",
"limit": null,
"store_wide": true,
"minimum_amount": null,
"expires_at": null,
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1,
"deleted_at": null
}
}
```
# Delete a coupon (/docs/api/coupons/delete-a-coupon)
This endpoint allows you to delete a coupon.
This will permanently delete the coupon.
## Endpoint
- Method: `DELETE`
- Path: `/v1/coupons/{coupon}`
- Full URL: `https://sell.app/api/v1/coupons/{coupon}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `coupon` (`integer`, required): The coupon path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"code": {
"type": "string"
},
"type": {
"type": "string"
},
"discount": {
"type": "string"
},
"limit": {
"type": "null"
},
"store_wide": {
"type": "boolean"
},
"minimum_amount": {
"type": "null"
},
"expires_at": {
"type": "null"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"deleted_at": {
"type": "null"
}
},
"required": [
"id",
"code",
"type",
"discount",
"limit",
"store_wide",
"minimum_amount",
"expires_at",
"created_at",
"updated_at",
"store_id",
"deleted_at"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 1,
"code": "BONANZA",
"type": "PERCENTAGE",
"discount": "80",
"limit": null,
"store_wide": true,
"minimum_amount": null,
"expires_at": null,
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1,
"deleted_at": null
}
}
```
# Overview (/docs/api/coupons)
Coupons help boost sales on your SellApp storefront — they allow you to attract new customers with exclusive offers and reward existing customers for their previous purchases.
On this page, we'll dive into the different coupon endpoints you can use to manage coupons programmatically. We'll look at how to create, update, and delete coupons.
## Endpoints [#endpoints]
* [List all coupons](/api/coupons/list-all-coupons)
* [Create a coupon](/api/coupons/create-a-coupon)
* [Retrieve a coupon](/api/coupons/retrieve-a-coupon)
* [Update a coupon](/api/coupons/update-a-coupon)
* [Delete a coupon](/api/coupons/delete-a-coupon)
## The coupon model [#the-coupon-model]
The coupon model contains all the information about the coupons stores have, including the type, code, and discount amount.
### Properties [#properties]
The unique identifier for the coupon.
The coupon code which the customer enters during checkout.
The type of coupon. Supported types:
* PERCENTAGE
* AMOUNT
The discount value related to the above type. Examples:
* PERCENTAGE: `50` *(in percentages)*
* AMOUNT: `5` *(in dollars)*
The total amount of times this coupon can be applied before it can no longer be used.
The scope of the coupon; if true it applies to all products in your store. If false, it only applies to certain products.
The minimum amount *(in dollars)* at which the coupon can be applied.
The time at which this coupon stops being usable.
The time at which this coupon was first created.
The time at which this coupon was last updated.
The ID of the store this coupon belongs to.
The time at which this coupon was deleted.
***
# List all coupons (/docs/api/coupons/list-all-coupons)
This endpoint allows you to retrieve a paginated list of all your coupons. By default, a maximum of fifteen coupons are shown per page.
## Endpoint
- Method: `GET`
- Path: `/v1/coupons`
- Full URL: `https://sell.app/api/v1/coupons`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
None.
## Query Parameters
- `limit` (`integer`, optional): Limit the number of blacklist rules returned.
- `page` (`integer`, optional): The page number you are attempting to access.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"code": {
"type": "string"
},
"type": {
"type": "string"
},
"discount": {
"type": "string"
},
"limit": {
"type": "null"
},
"store_wide": {
"type": "boolean"
},
"minimum_amount": {
"type": "null"
},
"expires_at": {
"type": "null"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"deleted_at": {
"type": "null"
}
},
"required": [
"id",
"code",
"type",
"discount",
"limit",
"store_wide",
"minimum_amount",
"expires_at",
"created_at",
"updated_at",
"store_id",
"deleted_at"
]
}
},
"links": {
"type": "object",
"properties": {}
},
"meta": {
"type": "object",
"properties": {}
}
},
"required": [
"data",
"links",
"meta"
]
}
```
Example:
```json
{
"data": [
{
"id": 1,
"code": "BONANZA",
"type": "PERCENTAGE",
"discount": "80",
"limit": null,
"store_wide": true,
"minimum_amount": null,
"expires_at": null,
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1,
"deleted_at": null
}
],
"links": {},
"meta": {}
}
```
# Retrieve a coupon (/docs/api/coupons/retrieve-a-coupon)
This endpoint allows you to retrieve a specific coupon by providing the unique identifier. Refer to [the list](/api/coupons#the-coupon-model) to see which properties are included with coupon objects.
## Endpoint
- Method: `GET`
- Path: `/v1/coupons/{coupon}`
- Full URL: `https://sell.app/api/v1/coupons/{coupon}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `coupon` (`integer`, required): The coupon path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"code": {
"type": "string"
},
"type": {
"type": "string"
},
"discount": {
"type": "string"
},
"limit": {
"type": "null"
},
"store_wide": {
"type": "boolean"
},
"minimum_amount": {
"type": "null"
},
"expires_at": {
"type": "null"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"deleted_at": {
"type": "null"
}
},
"required": [
"id",
"code",
"type",
"discount",
"limit",
"store_wide",
"minimum_amount",
"expires_at",
"created_at",
"updated_at",
"store_id",
"deleted_at"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 1,
"code": "BONANZA",
"type": "PERCENTAGE",
"discount": "80",
"limit": null,
"store_wide": true,
"minimum_amount": null,
"expires_at": null,
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1,
"deleted_at": null
}
}
```
# Update a coupon (/docs/api/coupons/update-a-coupon)
This endpoint allows you to perform an update on a coupon.
## Endpoint
- Method: `PATCH`
- Path: `/v1/coupons/{coupon}`
- Full URL: `https://sell.app/api/v1/coupons/{coupon}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `coupon` (`integer`, required): The coupon path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"code": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"PERCENTAGE",
"AMOUNT"
]
},
"discount": {
"type": "number"
},
"store_wide": {
"type": "boolean"
},
"products": {
"type": "array",
"minItems": 1,
"items": {
"type": "integer"
}
},
"limit": {
"type": [
"integer",
"null"
]
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"minimum_amount": {
"type": [
"number",
"null"
]
}
}
}
```
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"code": {
"type": "string"
},
"type": {
"type": "string"
},
"discount": {
"type": "string"
},
"limit": {
"type": "null"
},
"store_wide": {
"type": "boolean"
},
"minimum_amount": {
"type": "null"
},
"expires_at": {
"type": "null"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"deleted_at": {
"type": "null"
}
},
"required": [
"id",
"code",
"type",
"discount",
"limit",
"store_wide",
"minimum_amount",
"expires_at",
"created_at",
"updated_at",
"store_id",
"deleted_at"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 1,
"code": "BAZINGA",
"type": "PERCENTAGE",
"discount": "80",
"limit": null,
"store_wide": true,
"minimum_amount": null,
"expires_at": null,
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1,
"deleted_at": null
}
}
```
# Overview (/docs/api/feedback)
Feedback helps give your storefront more legitimacy by informing potential customers about your product quality and seller reputation. The better your feedback, the higher the likelihood visitors turn into customers.
On this page, we'll dive into the different feedback endpoints you can use to manage feedback programmatically. We'll look at how to query and reply to feedback.
## Endpoints [#endpoints]
* [List all feedback](/api/feedback/list-all-feedback)
* [Retrieve specific feedback](/api/feedback/retrieve-specific-feedback)
* [Reply to feedback](/api/feedback/reply-to-feedback)
## The feedback model [#the-feedback-model]
The feedback model contains all the information about your store's feedback, including the feedback's message, reply, and rating.
### Properties [#properties]
The unique identifier for the feedback.
The feedback sentiment, one of three:
* `POSITIVE`
* `NEUTRAL`
* `NEGATIVE`
The feedback rating, from one to five.
The time at which this feedback was deleted.
The time at which this feedback was first created.
The time at which this feedback was last updated.
The ID of the product this feedback belongs to.
The ID of the order this feedback belongs to.
The ID of the store this feedback belongs to.
Array of metadata related to the feedback; shows whether the feedback was imported.
The message the customer left in this feedback.
The reply to the feedback the storefront left.
Whether the feedback was automatic or not, one of two:
* `1`: Feedback is automatically left
* `0`: Feedback is not automatically left
***
# List all feedback (/docs/api/feedback/list-all-feedback)
This endpoint allows you to retrieve a paginated list of all your feedback received. By default, a maximum of fifteen feedback are shown per page.
## Endpoint
- Method: `GET`
- Path: `/v1/feedback`
- Full URL: `https://sell.app/api/v1/feedback`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
None.
## Query Parameters
- `limit` (`integer`, optional): Limit the number of blacklist rules returned.
- `page` (`integer`, optional): The page number you are attempting to access.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"feedback": {
"type": "string"
},
"rating": {
"type": "integer"
},
"deleted_at": {
"type": "null"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"listing_id": {
"type": "integer"
},
"invoice_id": {
"type": "integer"
},
"store_id": {
"type": "integer"
},
"metadata": {
"type": "null"
},
"message": {
"type": "string"
},
"reply": {
"type": "string"
},
"is_automatic": {
"type": "integer"
}
},
"required": [
"id",
"feedback",
"rating",
"deleted_at",
"created_at",
"updated_at",
"listing_id",
"invoice_id",
"store_id",
"metadata",
"message",
"reply",
"is_automatic"
]
}
},
"links": {
"type": "object",
"properties": {}
},
"meta": {
"type": "object",
"properties": {}
}
},
"required": [
"data",
"links",
"meta"
]
}
```
Example:
```json
{
"data": [
{
"id": 1,
"feedback": "POSITIVE",
"rating": 5,
"deleted_at": null,
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"listing_id": 1,
"invoice_id": 1,
"store_id": 1,
"metadata": null,
"message": "This product changed my life. My ex-wife wanted me back, my kids started talking to me, and my boss gave me a raise too!",
"reply": "The power of selling your soul to the Illuminati!",
"is_automatic": 1
}
],
"links": {},
"meta": {}
}
```
# Reply to feedback (/docs/api/feedback/reply-to-feedback)
This endpoint allows you to reply to a given feedback.
## Endpoint
- Method: `PATCH`
- Path: `/v1/feedback/{feedback}`
- Full URL: `https://sell.app/api/v1/feedback/{feedback}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `feedback` (`integer`, required): The feedback path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"reply": {
"type": "string"
}
},
"required": [
"reply"
]
}
```
Example:
```json
{
"reply": "Do not sell your soul, kids!"
}
```
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"feedback": {
"type": "string"
},
"rating": {
"type": "integer"
},
"deleted_at": {
"type": "null"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"listing_id": {
"type": "integer"
},
"invoice_id": {
"type": "integer"
},
"store_id": {
"type": "integer"
},
"metadata": {
"type": "null"
},
"message": {
"type": "string"
},
"reply": {
"type": "string"
},
"is_automatic": {
"type": "integer"
}
},
"required": [
"id",
"feedback",
"rating",
"deleted_at",
"created_at",
"updated_at",
"listing_id",
"invoice_id",
"store_id",
"metadata",
"message",
"reply",
"is_automatic"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 1,
"feedback": "POSITIVE",
"rating": 5,
"deleted_at": null,
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"listing_id": 1,
"invoice_id": 1,
"store_id": 1,
"metadata": null,
"message": "This product changed my life. My ex-wife wanted me back, my kids started talking to me, and my boss gave me a raise too!",
"reply": "Do not sell your soul, kids!",
"is_automatic": 1
}
}
```
# Retrieve specific feedback (/docs/api/feedback/retrieve-specific-feedback)
This endpoint allows you to retrieve a specific feedback by providing the unique identifier. Refer to [the list](/api/feedback#the-feedback-model) to see which properties are included with feedback objects.
## Endpoint
- Method: `GET`
- Path: `/v1/feedback/{feedback}`
- Full URL: `https://sell.app/api/v1/feedback/{feedback}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `feedback` (`integer`, required): The feedback path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"feedback": {
"type": "string"
},
"rating": {
"type": "integer"
},
"deleted_at": {
"type": "null"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"listing_id": {
"type": "integer"
},
"invoice_id": {
"type": "integer"
},
"store_id": {
"type": "integer"
},
"metadata": {
"type": "null"
},
"message": {
"type": "string"
},
"reply": {
"type": "string"
},
"is_automatic": {
"type": "integer"
}
},
"required": [
"id",
"feedback",
"rating",
"deleted_at",
"created_at",
"updated_at",
"listing_id",
"invoice_id",
"store_id",
"metadata",
"message",
"reply",
"is_automatic"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 1,
"feedback": "POSITIVE",
"rating": 5,
"deleted_at": null,
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"listing_id": 1,
"invoice_id": 1,
"store_id": 1,
"metadata": null,
"message": "This product changed my life. My ex-wife wanted me back, my kids started talking to me, and my boss gave me a raise too!",
"reply": "The power of selling your soul to the Illuminati!",
"is_automatic": 1
}
}
```
# Add products to group (/docs/api/groups/add-products-to-group)
This endpoint allows you to add products to an existing group. See the code examples for how to add products to an existing group with the SellApp API.
## Endpoint
- Method: `POST`
- Path: `/v2/groups/{group}/products/attach`
- Full URL: `https://sell.app/api/v2/groups/{group}/products/attach`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `group` (`integer`, required): The group path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"resources": {
"type": "array",
"items": {
"type": "integer"
}
}
},
"required": [
"resources"
]
}
```
Example:
```json
{
"resources": [
1
]
}
```
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"attached": {
"type": "array",
"items": {
"type": "integer"
}
}
},
"required": [
"attached"
]
}
```
Example:
```json
{
"attached": [
1
]
}
```
# Create a group (/docs/api/groups/create-a-group)
This endpoint allows you to create a new group. See the code examples for how to create a new group with the SellApp API.
## Endpoint
- Method: `POST`
- Path: `/v2/groups`
- Full URL: `https://sell.app/api/v2/groups`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
None.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"title": {
"type": "string"
},
"unlisted": {
"type": "boolean"
},
"order": {
"type": [
"integer",
"null"
]
}
},
"required": [
"title",
"unlisted"
]
}
```
### Content Type: `multipart/form-data`
Schema:
```json
{
"type": "object",
"properties": {
"title": {
"type": "string"
},
"unlisted": {
"type": "boolean"
},
"order": {
"type": [
"integer",
"null"
]
},
"image": {
"type": "string",
"format": "binary"
}
},
"required": [
"title",
"unlisted"
]
}
```
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"order": {
"type": "integer"
},
"image": {
"type": "null"
},
"unlisted": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"section_id": {
"type": "null"
},
"section_order": {
"type": "null"
},
"products_linked": {
"type": "integer"
},
"products": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"title",
"order",
"image",
"unlisted",
"created_at",
"updated_at",
"store_id",
"section_id",
"section_order",
"products_linked",
"products"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 1,
"title": "Rat race",
"order": 1,
"image": null,
"unlisted": false,
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1,
"section_id": null,
"section_order": null,
"products_linked": 0,
"products": []
}
}
```
# Delete a group (/docs/api/groups/delete-a-group)
This endpoint allows you to delete a group.
This will permanently delete the group and its details.
## Endpoint
- Method: `DELETE`
- Path: `/v2/groups/{group}`
- Full URL: `https://sell.app/api/v2/groups/{group}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `group` (`integer`, required): The group path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"order": {
"type": "integer"
},
"image": {
"type": "null"
},
"unlisted": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"section_id": {
"type": "null"
},
"section_order": {
"type": "null"
},
"products_linked": {
"type": "integer"
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"id",
"title",
"description"
]
}
}
},
"required": [
"id",
"title",
"order",
"image",
"unlisted",
"created_at",
"updated_at",
"store_id",
"section_id",
"section_order",
"products_linked",
"products"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 1,
"title": "Rat race",
"order": 1,
"image": null,
"unlisted": false,
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1,
"section_id": null,
"section_order": null,
"products_linked": 1,
"products": [
{
"id": "1",
"title": "This will make me rich!",
"description": "I am sure of it, Pinky."
}
]
}
}
```
# Overview (/docs/api/groups)
Groups are a way to help make your storefront navigable in SellApp — they are a collection of products you've grouped together in a tidy bunch.
On this page, we'll dive into the different group endpoints you can use to manage groups programmatically. We'll look at how to query, create, update, and delete groups, as well as how to add and remove products within groups.
## Endpoints [#endpoints]
* [List all groups](/api/groups/list-all-groups)
* [Create a group](/api/groups/create-a-group)
* [Retrieve a group](/api/groups/retrieve-a-group)
* [Update a group](/api/groups/update-a-group)
* [Delete a group](/api/groups/delete-a-group)
* [Add products to group](/api/groups/add-products-to-group)
* [Remove products from group](/api/groups/remove-products-from-group)
* [List all products within group](/api/groups/list-all-products-within-group)
* [List specific product within group](/api/groups/list-specific-product-within-group)
## The group model [#the-group-model]
The group model contains all the information about your groups, including what products are in the group and the group's name, description, and image.
### Properties [#properties]
The unique identifier for the group.
The group title.
The order rank of the group.
The image belonging to the group.
Whether the group is unlisted or not. If set to true, the group will only be accessible via a direct link.
The time at which this group was first created.
The time at which this group was last updated.
The ID of the store this group belongs to.
The ID of the section this group belongs to.
The order rank of the group within the section it belongs to.
The amount of products linked to this group.
The products linked to this group, containing three types of info:
* `id`: The product ID
* `title`: The product title
* `description`: The product description
***
# List all groups (/docs/api/groups/list-all-groups)
This endpoint allows you to retrieve a paginated list of all your groups. By default, a maximum of fifteen groups are shown per page.
## Endpoint
- Method: `GET`
- Path: `/v2/groups`
- Full URL: `https://sell.app/api/v2/groups`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
None.
## Query Parameters
- `limit` (`integer`, optional): Limit the number of blacklist rules returned.
- `page` (`integer`, optional): The page number you are attempting to access.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"order": {
"type": "integer"
},
"image": {
"type": "null"
},
"unlisted": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"section_id": {
"type": "null"
},
"section_order": {
"type": "null"
},
"products_linked": {
"type": "integer"
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"id",
"title",
"description"
]
}
}
},
"required": [
"id",
"title",
"order",
"image",
"unlisted",
"created_at",
"updated_at",
"store_id",
"section_id",
"section_order",
"products_linked",
"products"
]
}
},
"links": {
"type": "object",
"properties": {}
},
"meta": {
"type": "object",
"properties": {}
}
},
"required": [
"data",
"links",
"meta"
]
}
```
Example:
```json
{
"data": [
{
"id": 1,
"title": "Rat race",
"order": 1,
"image": null,
"unlisted": false,
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1,
"section_id": null,
"section_order": null,
"products_linked": 1,
"products": [
{
"id": "1",
"title": "This will make me rich!",
"description": "I am sure of it, Pinky."
}
]
}
],
"links": {},
"meta": {}
}
```
# List all products within group (/docs/api/groups/list-all-products-within-group)
This endpoint allows you to retrieve a paginated list of all the products within your group. By default, a maximum of fifteen products are shown per page.
## Endpoint
- Method: `GET`
- Path: `/v2/groups/{group}/products`
- Full URL: `https://sell.app/api/v2/groups/{group}/products`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `group` (`integer`, required): The group path parameter.
## Query Parameters
- `limit` (`integer`, optional): Limit the number of blacklist rules returned.
- `page` (`integer`, optional): The page number you are attempting to access.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"slug": {
"type": "string"
},
"description": {
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "string"
}
},
"order": {
"type": "integer"
},
"visibility": {
"type": "string"
},
"delivery_text": {
"type": "null"
},
"additional_information": {
"type": "array",
"items": {
"type": "string"
}
},
"warranty": {
"type": "object",
"properties": {
"text": {
"type": "string"
},
"time": {
"type": "null"
},
"preferredUnit": {
"type": "string"
}
},
"required": [
"text",
"time",
"preferredUnit"
]
},
"other_settings": {
"type": "array",
"items": {
"type": "string"
}
},
"deleted_at": {
"type": "null"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"category_id": {
"type": "null"
},
"section_id": {
"type": "null"
},
"section_order": {
"type": "null"
},
"is_discoverable": {
"type": "integer"
},
"pivot": {
"type": "object",
"properties": {
"group_id": {
"type": "integer"
},
"listing_id": {
"type": "integer"
},
"order": {
"type": "integer"
}
},
"required": [
"group_id",
"listing_id",
"order"
]
},
"default_price": {
"type": "object",
"properties": {
"price": {
"type": "string"
},
"currency": {
"type": "string"
}
},
"required": [
"price",
"currency"
]
}
},
"required": [
"id",
"title",
"slug",
"description",
"images",
"order",
"visibility",
"delivery_text",
"additional_information",
"warranty",
"other_settings",
"deleted_at",
"created_at",
"updated_at",
"store_id",
"category_id",
"section_id",
"section_order",
"is_discoverable",
"pivot",
"default_price"
]
}
},
"links": {
"type": "object",
"properties": {}
},
"meta": {
"type": "object",
"properties": {}
}
},
"required": [
"data",
"links",
"meta"
]
}
```
Example:
```json
{
"data": [
{
"id": 1,
"title": "This will make me rich!",
"slug": "serial",
"description": "I am sure of it, Pinky.
",
"images": [],
"order": 1,
"visibility": "PUBLIC",
"delivery_text": null,
"additional_information": [],
"warranty": {
"text": "",
"time": null,
"preferredUnit": "MINUTES"
},
"other_settings": [],
"deleted_at": null,
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1,
"category_id": null,
"section_id": null,
"section_order": null,
"is_discoverable": 1,
"pivot": {
"group_id": 1,
"listing_id": 1,
"order": 1
},
"default_price": {
"price": "500",
"currency": "USD"
}
}
],
"links": {},
"meta": {}
}
```
# List specific product within group (/docs/api/groups/list-specific-product-within-group)
This endpoint allows you to retrieve a specific product from within a group.
## Endpoint
- Method: `GET`
- Path: `/v2/groups/{group}/products/{product}`
- Full URL: `https://sell.app/api/v2/groups/{group}/products/{product}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `group` (`integer`, required): The group path parameter.
- `product` (`integer`, required): The product path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"slug": {
"type": "string"
},
"description": {
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "string"
}
},
"order": {
"type": "integer"
},
"visibility": {
"type": "string"
},
"delivery_text": {
"type": "null"
},
"additional_information": {
"type": "array",
"items": {
"type": "string"
}
},
"warranty": {
"type": "object",
"properties": {
"text": {
"type": "string"
},
"time": {
"type": "null"
},
"preferredUnit": {
"type": "string"
}
},
"required": [
"text",
"time",
"preferredUnit"
]
},
"other_settings": {
"type": "array",
"items": {
"type": "string"
}
},
"deleted_at": {
"type": "null"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"category_id": {
"type": "null"
},
"section_id": {
"type": "null"
},
"section_order": {
"type": "null"
},
"is_discoverable": {
"type": "integer"
},
"pivot": {
"type": "object",
"properties": {
"group_id": {
"type": "integer"
},
"listing_id": {
"type": "integer"
},
"order": {
"type": "integer"
}
},
"required": [
"group_id",
"listing_id",
"order"
]
}
},
"required": [
"id",
"title",
"slug",
"description",
"images",
"order",
"visibility",
"delivery_text",
"additional_information",
"warranty",
"other_settings",
"deleted_at",
"created_at",
"updated_at",
"store_id",
"category_id",
"section_id",
"section_order",
"is_discoverable",
"pivot"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 1,
"title": "This will make me rich!",
"slug": "serial",
"description": "I am sure of it, Pinky.
",
"images": [],
"order": 1,
"visibility": "PUBLIC",
"delivery_text": null,
"additional_information": [],
"warranty": {
"text": "",
"time": null,
"preferredUnit": "MINUTES"
},
"other_settings": [],
"deleted_at": null,
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1,
"category_id": null,
"section_id": null,
"section_order": null,
"is_discoverable": 1,
"pivot": {
"group_id": 1,
"listing_id": 1,
"order": 1
}
}
}
```
# Remove products from group (/docs/api/groups/remove-products-from-group)
This endpoint allows you to remove products from a group.
## Endpoint
- Method: `DELETE`
- Path: `/v2/groups/{group}/products/detach`
- Full URL: `https://sell.app/api/v2/groups/{group}/products/detach`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `group` (`integer`, required): The group path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"resources": {
"type": "array",
"items": {
"type": "integer"
}
}
},
"required": [
"resources"
]
}
```
Example:
```json
{
"resources": [
1
]
}
```
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"detached": {
"type": "array",
"items": {
"type": "integer"
}
}
},
"required": [
"detached"
]
}
```
Example:
```json
{
"detached": [
1
]
}
```
# Retrieve a group (/docs/api/groups/retrieve-a-group)
This endpoint allows you to retrieve a specific group by providing the unique identifier. Refer to [the list](/api/groups#the-group-model) to see which properties are included with group objects.
## Endpoint
- Method: `GET`
- Path: `/v2/groups/{group}`
- Full URL: `https://sell.app/api/v2/groups/{group}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `group` (`integer`, required): The group path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"order": {
"type": "integer"
},
"image": {
"type": "null"
},
"unlisted": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"section_id": {
"type": "null"
},
"section_order": {
"type": "null"
},
"products_linked": {
"type": "integer"
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"id",
"title",
"description"
]
}
}
},
"required": [
"id",
"title",
"order",
"image",
"unlisted",
"created_at",
"updated_at",
"store_id",
"section_id",
"section_order",
"products_linked",
"products"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 1,
"title": "Rat race",
"order": 1,
"image": null,
"unlisted": false,
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1,
"section_id": null,
"section_order": null,
"products_linked": 1,
"products": [
{
"id": "1",
"title": "This will make me rich!",
"description": "I am sure of it, Pinky."
}
]
}
}
```
# Update a group (/docs/api/groups/update-a-group)
This endpoint allows you to perform an update on a group.
## Endpoint
- Method: `PATCH`
- Path: `/v2/groups/{group}`
- Full URL: `https://sell.app/api/v2/groups/{group}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `group` (`integer`, required): The group path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"title": {
"type": "string"
},
"unlisted": {
"type": "boolean"
},
"order": {
"type": [
"integer",
"null"
]
}
}
}
```
### Content Type: `multipart/form-data`
Schema:
```json
{
"type": "object",
"properties": {
"title": {
"type": "string"
},
"unlisted": {
"type": "boolean"
},
"order": {
"type": [
"integer",
"null"
]
},
"image": {
"type": "string",
"format": "binary"
}
}
}
```
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"order": {
"type": "integer"
},
"image": {
"type": "null"
},
"unlisted": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"section_id": {
"type": "null"
},
"section_order": {
"type": "null"
},
"products_linked": {
"type": "integer"
},
"products": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"title",
"order",
"image",
"unlisted",
"created_at",
"updated_at",
"store_id",
"section_id",
"section_order",
"products_linked",
"products"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 1,
"title": "Rat race",
"order": 1,
"image": null,
"unlisted": true,
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1,
"section_id": null,
"section_order": null,
"products_linked": 0,
"products": []
}
}
```
# Overview (/docs/api/license-instances)
The Licenses API endpoints helps you manage licenses purchased through your store. You can activate licenses for specific instances, validate existing instances, and manage the associated instances. This is useful for integrating license checks directly into your software or external systems.
License instances are part of a [license key](/api/licenses). Each license key
can be linked to multiple instances. Whenever you activate a license key, you
create a new instance of the license key.
## Endpoints [#endpoints]
* [List license instances](/api/license-instances/list-license-instances)
* [Retrieve a license instance](/api/license-instances/retrieve-a-license-instance)
## The license key model [#the-license-key-model]
The license key model represents a single license key purchased by a customer.
### Properties [#properties]
*(read-only)* The unique identifier for the license key.
*(read-only)* The actual license key string
The maximum number of instances this key can be activated on. `null` means unlimited activations.
Whether the license key is currently active which you can modify via the API and which is unrelated to the status. Inactive keys cannot be activated or validated successfully.
*(read-only)* The status of the license key, one of: `ACTIVE`, `INACTIVE`, `EXPIRED`
The timestamp when the license key expires. `null` means the license will never expire.
Whether the license key is expired.
*(read-only)* The ID of the store this license key belongs to.
*(read-only)* The ID of the order associated with this license key.
*(read-only)* The ID of the associated invoice V2, if applicable.
*(read-only)* The ID of the product this license is for.
*(read-only)* The ID of the specific product variant this license is for.
*(read-only)* The ID of the customer that purchased this license key.
*(read-only)* The ID of the associated subscription, if applicable.
*(read-only)* Time at which the license key was created.
*(read-only)* Time at which the license key was last updated.
## The license instance model [#the-license-instance-model]
The license instance model represents a single activation of a license key on a specific device or identifier.
### Properties [#properties-1]
*(read-only)* The unique identifier (UUID) of the license instance. **This is the `instance_id` used for validation.**
*(read-only)* The unique identifier for the parent license key which this instance is linked to.
*(read-only)* The name provided during activation, which you can use to identify this instance (e.g., the customer's email or HWID).
*(read-only)* The ID of the store this instance belongs to.
*(read-only)* Time at which the instance was created (activation time).
*(read-only)* Time at which the instance was last updated.
***
# List license instances (/docs/api/license-instances/list-license-instances)
Retrieves a paginated list of all active instances (activations) associated with a specific license key.
Refer to [the license instance model](../license-instances#the-license-instance-model) section for details on the returned object structure.
## Endpoint
- Method: `GET`
- Path: `/v2/license-keys/{license_key}/instances`
- Full URL: `https://sell.app/api/v2/license-keys/{license_key}/instances`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `license_key` (`integer`, required): The license key path parameter.
## Query Parameters
- `limit` (`integer`, optional): Limit the number of blacklist rules returned.
- `page` (`integer`, optional): The page number you are attempting to access.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"license_key_id": {
"type": "integer"
},
"name": {
"type": "string"
},
"store_id": {
"type": "integer"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"license_key_id",
"name",
"store_id",
"created_at",
"updated_at"
]
}
},
"links": {
"type": "object",
"properties": {}
},
"meta": {
"type": "object",
"properties": {}
}
},
"required": [
"data",
"links",
"meta"
]
}
```
Example:
```json
{
"data": [
{
"id": "9ebd37af-2077-42f9-9f88-d96cfc6ef1a8",
"license_key_id": 1,
"name": "zezima@osrs.com",
"store_id": 1,
"created_at": "2025-04-22T20:53:22.000000Z",
"updated_at": "2025-04-22T20:53:22.000000Z"
}
],
"links": {},
"meta": {}
}
```
# Retrieve a license instance (/docs/api/license-instances/retrieve-a-license-instance)
Retrieves the details of a specific license instance using the license key ID and the instance's unique UUID.
Refer to [the license instance model](../license-instances#the-license-instance-model) section for details on the returned object structure.
## Endpoint
- Method: `GET`
- Path: `/v2/license-keys/{license_key}/instances/{instance}`
- Full URL: `https://sell.app/api/v2/license-keys/{license_key}/instances/{instance}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `license_key` (`integer`, required): The license key path parameter.
- `instance` (`string`, required): The instance path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"license_key_id": {
"type": "integer"
},
"name": {
"type": "string"
},
"store_id": {
"type": "integer"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"license_key_id",
"name",
"store_id",
"created_at",
"updated_at"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": "9ebd37af-2077-42f9-9f88-d96cfc6ef1a8",
"license_key_id": 1,
"name": "zezima@osrs.com",
"store_id": 1,
"created_at": "2025-04-22T20:53:22.000000Z",
"updated_at": "2025-04-22T20:53:22.000000Z"
}
}
```
# Create a checkout session (/docs/api/invoices/create-a-checkout-session)
This endpoint creates a checkout session for a pending invoice.
A practical example:
1. You first create an invoice via the [the create an invoice](#create-an-invoice) endpoint
2. Then generate a checkout session via this endpoint.
3. Finally, you retrieve the `payment_url` you receive in the response, and show this to your customer as a button, or redirect them to the respective URL.
If the invoice is priced as zero, which means it's a free product, the invoice will instead be marked as completed.
See the code examples for how to create a new invoice payment URL with the SellApp API.
## Endpoint
- Method: `POST`
- Path: `/v2/invoices/{invoice}/checkout`
- Full URL: `https://sell.app/api/v2/invoices/{invoice}/checkout`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `invoice` (`integer`, required): The invoice path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"message": {
"type": "string"
},
"payment_url": {
"type": "string"
},
"invoice": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"payment": {
"type": "object",
"properties": {
"fee": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"gateway": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"customer_email": {
"type": "string"
},
"transaction_id": {
"type": "string"
},
"checkout_url": {
"type": "string"
}
},
"required": [
"total",
"customer_email",
"transaction_id",
"checkout_url"
]
},
"type": {
"type": "string"
}
},
"required": [
"data",
"type"
]
},
"subtotal": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"full_price": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"original_amount": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
}
},
"required": [
"fee",
"gateway",
"subtotal",
"expires_at",
"full_price",
"original_amount"
]
},
"status": {
"type": "object",
"properties": {
"history": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "object",
"properties": {
"setAt": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"setAt",
"status",
"updatedAt"
]
}
},
"required": [
"history",
"status"
]
},
"webhooks": {
"type": "array",
"items": {
"type": "string"
}
},
"feedback": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"coupon_id": {
"type": "null"
},
"subscription_id": {
"type": "null"
},
"customer_information": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"email": {
"type": "string"
},
"country": {
"type": "string"
},
"location": {
"type": "string"
},
"ip": {
"type": "string"
},
"proxied": {
"type": "boolean"
},
"browser_agent": {
"type": "string"
},
"vat": {
"type": "object",
"properties": {
"amount": {
"type": "integer"
},
"country": {
"type": "string"
}
},
"required": [
"amount",
"country"
]
}
},
"required": [
"id",
"email",
"country",
"location",
"ip",
"proxied",
"browser_agent",
"vat"
]
}
},
"required": [
"id",
"payment",
"status",
"webhooks",
"feedback",
"created_at",
"updated_at",
"store_id",
"coupon_id",
"subscription_id",
"customer_information"
]
}
},
"required": [
"message",
"invoice"
]
}
```
Example:
```json
{
"message": "A new payment session has been generated.",
"payment_url": "https://commerce.coinbase.com/charges/CQEGF35V",
"invoice": {
"id": 1,
"payment": {
"fee": {
"base": "0",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "0",
"inclusive": "0"
}
},
"gateway": {
"data": {
"total": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"customer_email": "customer@example.com",
"transaction_id": "CQEGF35V",
"checkout_url": "https://commerce.coinbase.com/charges/CQEGF35V"
},
"type": "COINBASE"
},
"subtotal": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"expires_at": "2024-01-09T23:50:11.000000Z",
"full_price": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"original_amount": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
}
},
"status": {
"history": [],
"status": {
"setAt": "2024-01-09T14:50:11.000000Z",
"status": "PENDING",
"updatedAt": "2024-01-09T18:00:50.000000Z"
}
},
"webhooks": [],
"feedback": "",
"created_at": "2024-01-09T14:50:11.000000Z",
"updated_at": "2024-01-09T18:00:50.000000Z",
"store_id": 1,
"coupon_id": null,
"subscription_id": null,
"customer_information": {
"id": 123,
"email": "customer@example.com",
"country": "Germany",
"location": "Munich",
"ip": "1.3.3.7",
"proxied": false,
"browser_agent": "Mozilla/4.9 (Windows 98; sl-SI; rv:1.9.1.20) Gecko/20110422 Firefox/21.0",
"vat": {
"amount": 0,
"country": "DE"
}
}
}
}
```
### 201
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"message": {
"type": "string"
},
"payment_url": {
"type": "string"
},
"invoice": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"payment": {
"type": "object",
"properties": {
"fee": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"gateway": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"customer_email": {
"type": "string"
},
"transaction_id": {
"type": "string"
},
"checkout_url": {
"type": "string"
}
},
"required": [
"total",
"customer_email",
"transaction_id",
"checkout_url"
]
},
"type": {
"type": "string"
}
},
"required": [
"data",
"type"
]
},
"subtotal": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"full_price": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"original_amount": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
}
},
"required": [
"fee",
"gateway",
"subtotal",
"expires_at",
"full_price",
"original_amount"
]
},
"status": {
"type": "object",
"properties": {
"history": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "object",
"properties": {
"setAt": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"setAt",
"status",
"updatedAt"
]
}
},
"required": [
"history",
"status"
]
},
"webhooks": {
"type": "array",
"items": {
"type": "string"
}
},
"feedback": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"coupon_id": {
"type": "null"
},
"subscription_id": {
"type": "null"
},
"customer_information": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"email": {
"type": "string"
},
"country": {
"type": "string"
},
"location": {
"type": "string"
},
"ip": {
"type": "string"
},
"proxied": {
"type": "boolean"
},
"browser_agent": {
"type": "string"
},
"vat": {
"type": "object",
"properties": {
"amount": {
"type": "integer"
},
"country": {
"type": "string"
}
},
"required": [
"amount",
"country"
]
}
},
"required": [
"id",
"email",
"country",
"location",
"ip",
"proxied",
"browser_agent",
"vat"
]
}
},
"required": [
"id",
"payment",
"status",
"webhooks",
"feedback",
"created_at",
"updated_at",
"store_id",
"coupon_id",
"subscription_id",
"customer_information"
]
}
},
"required": [
"message",
"invoice"
]
}
```
Example:
```json
{
"message": "A new payment session has been generated.",
"payment_url": "https://commerce.coinbase.com/charges/CQEGF35V",
"invoice": {
"id": 1,
"payment": {
"fee": {
"base": "0",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "0",
"inclusive": "0"
}
},
"gateway": {
"data": {
"total": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"customer_email": "customer@example.com",
"transaction_id": "CQEGF35V",
"checkout_url": "https://commerce.coinbase.com/charges/CQEGF35V"
},
"type": "COINBASE"
},
"subtotal": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"expires_at": "2024-01-09T23:50:11.000000Z",
"full_price": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"original_amount": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
}
},
"status": {
"history": [],
"status": {
"setAt": "2024-01-09T14:50:11.000000Z",
"status": "PENDING",
"updatedAt": "2024-01-09T18:00:50.000000Z"
}
},
"webhooks": [],
"feedback": "",
"created_at": "2024-01-09T14:50:11.000000Z",
"updated_at": "2024-01-09T18:00:50.000000Z",
"store_id": 1,
"coupon_id": null,
"subscription_id": null,
"customer_information": {
"id": 123,
"email": "customer@example.com",
"country": "Germany",
"location": "Munich",
"ip": "1.3.3.7",
"proxied": false,
"browser_agent": "Mozilla/4.9 (Windows 98; sl-SI; rv:1.9.1.20) Gecko/20110422 Firefox/21.0",
"vat": {
"amount": 0,
"country": "DE"
}
}
}
}
```
# Create an invoice (/docs/api/invoices/create-an-invoice)
This endpoint allows you to create a new invoice. See the code examples for how to create a new invoice with the SellApp API.
The response now includes a top-level `checkout` field when a checkout URL is already available for the newly created invoice.
## Endpoint
- Method: `POST`
- Path: `/v2/invoices`
- Full URL: `https://sell.app/api/v2/invoices`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
None.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"customer_email": {
"type": "string",
"format": "email"
},
"customer_ip": {
"type": [
"string",
"null"
]
},
"payment_method": {
"type": "string",
"enum": [
"AUTHNET",
"BTCPAY",
"CASHAPP",
"COINBASE",
"PADDLE",
"PAYDASH",
"PAYPAL",
"PAYSTACK",
"SQUARE",
"STRIPE",
"VENMO",
"NMI",
"LIFI",
"BTC",
"LTC",
"ETH",
"XMR",
"SOL",
"ADA",
"BNB",
"TRX",
"MATIC",
"ETH_USDT",
"ETH_USDC",
"ETH_UNI",
"ETH_SHIB",
"ETH_DAI",
"BNB_USDT",
"BNB_USDC",
"TRX_USDT",
"TRX_USDC",
"SOL_USDT",
"SOL_USDC"
]
},
"coupon": {
"type": "string"
},
"vat_id": {
"type": "string"
},
"country": {
"type": "string"
},
"affiliate": {
"type": [
"string",
"null"
]
},
"extra": {
"type": "object",
"properties": {
"amount": {
"type": "integer"
},
"currency": {
"type": "string"
}
},
"required": [
"amount",
"currency"
]
},
"product_variants": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"quantity": {
"type": "integer"
},
"additional_information": {
"type": "object",
"additionalProperties": true
},
"fill_once": {
"type": "boolean"
}
},
"required": [
"quantity"
]
}
}
},
"required": [
"customer_email",
"payment_method",
"product_variants"
]
}
```
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"payment": {
"type": "object",
"properties": {
"fee": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"gateway": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"customer_email": {
"type": "string"
},
"transaction_id": {
"type": "string"
}
},
"required": [
"total",
"customer_email",
"transaction_id"
]
},
"type": {
"type": "string"
}
},
"required": [
"data",
"type"
]
},
"subtotal": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"full_price": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"original_amount": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
}
},
"required": [
"fee",
"gateway",
"subtotal",
"expires_at",
"full_price",
"original_amount"
]
},
"status": {
"type": "object",
"properties": {
"history": {
"type": "array",
"items": {
"type": "object",
"properties": {
"setAt": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"setAt",
"status",
"updatedAt"
]
}
},
"status": {
"type": "object",
"properties": {
"setAt": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"setAt",
"status",
"updatedAt"
]
}
},
"required": [
"history",
"status"
]
},
"webhooks": {
"type": "array",
"items": {
"type": "string"
}
},
"feedback": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"coupon_id": {
"type": "null"
},
"subscription_id": {
"type": "null"
},
"checkout": {
"type": "string"
},
"customer_information": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"email": {
"type": "string"
},
"country": {
"type": "string"
},
"location": {
"type": "string"
},
"ip": {
"type": "string"
},
"proxied": {
"type": "boolean"
},
"browser_agent": {
"type": "string"
},
"vat": {
"type": "object",
"properties": {
"amount": {
"type": "integer"
},
"country": {
"type": "string"
}
},
"required": [
"amount",
"country"
]
}
},
"required": [
"id",
"email",
"country",
"location",
"ip",
"proxied",
"browser_agent",
"vat"
]
}
},
"required": [
"id",
"payment",
"status",
"webhooks",
"feedback",
"created_at",
"updated_at",
"store_id",
"coupon_id",
"subscription_id",
"checkout",
"customer_information"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 1,
"payment": {
"fee": {
"base": "0",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "0",
"inclusive": "0"
}
},
"gateway": {
"data": {
"total": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"customer_email": "customer@example.com",
"transaction_id": "CQEGF35V"
},
"type": "COINBASE"
},
"subtotal": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"expires_at": "2024-01-09T23:50:11.000000Z",
"full_price": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"original_amount": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
}
},
"status": {
"history": [
{
"setAt": "2024-01-09T14:50:11.000000Z",
"status": "PENDING",
"updatedAt": "2024-01-09T18:00:50.000000Z"
}
],
"status": {
"setAt": "2024-01-09T18:00:50.000000Z",
"status": "COMPLETED",
"updatedAt": "2024-01-09T18:00:50.000000Z"
}
},
"webhooks": [],
"feedback": "",
"created_at": "2024-01-09T14:50:11.000000Z",
"updated_at": "2024-01-09T18:00:50.000000Z",
"store_id": 1,
"coupon_id": null,
"subscription_id": null,
"checkout": "https://checkout.example.com/cashapp",
"customer_information": {
"id": 123,
"email": "customer@example.com",
"country": "Germany",
"location": "Munich",
"ip": "1.3.3.7",
"proxied": false,
"browser_agent": "Mozilla/4.9 (Windows 98; sl-SI; rv:1.9.1.20) Gecko/20110422 Firefox/21.0",
"vat": {
"amount": 0,
"country": "DE"
}
}
}
}
```
# Overview (/docs/api/invoices)
Invoices are orders placed by customers. They contain all the info you might need for each order, from the total purchase amount, customer information, and the product(s) delivered.
On this page, we'll dive into the different invoice endpoints you can use to manage invoices programmatically. We'll look at how to view, create, and update invoices.
## Endpoints [#endpoints]
* [List all invoices](/api/invoices/list-all-invoices)
* [Search invoices](/api/invoices/search-invoices)
* [Create an invoice](/api/invoices/create-an-invoice)
* [Retrieve an invoice](/api/invoices/retrieve-an-invoice)
* [Create a checkout session](/api/invoices/create-a-checkout-session)
* [View invoice deliverables](/api/invoices/view-invoice-deliverables)
* [Mark pending invoice completed](/api/invoices/mark-pending-invoice-completed)
* [Mark pending invoice voided](/api/invoices/mark-pending-invoice-voided)
* [Issue replacement for completed invoice](/api/invoices/issue-replacement-for-completed-invoice)
## The invoice model [#the-invoice-model]
The invoice model contains all the information about the invoices stores have, including the type, code, and discount amount.
### Properties [#properties]
The unique identifier for the invoice.
The array of general payment details. Consists of the following parts:
* `fee` Displays the platform fee associated with this invoice.
* `gateway` Contains payment gateway type, transaction ID, checkout URL, and payment-method-specific metadata such as crypto addresses and requested / received crypto amounts.
* `subtotal` Payment subtotal calculation, contains currency, VAT, and total.
* `expires_at` At which time the invoice expires and no longer becomes payable.
* `full_price` Shows the full price of the invoice and includes modifiers such as extra amounts (Pay What You Want).
* `original_amount` Displays the original amount of the invoice and excludes modifiers such as extra amounts (Pay What You Want).
The historical array of the invoice's status. Consists of two parts:
* `history` Array of historical order statuses.
* `status` Current order status details.
The webhook details, if set.
The customer order feedback, if made.
The time at which this invoice was first created.
The time at which this invoice was last updated.
The ID of the store this invoice belongs to.
The ID of the coupon applied to this order, if set.
The ID of the subscription belonging to the invoice, if set.
The associated customer's information, consists of:
* `id` SellApp user ID *(if logged in)*.
* `email` Customer email.
* `country` Customer country.
* `location` Customer location *(city level)*.
* `ip` Customer IP.
* `proxied` Boolean; whether the customer is using IP obfuscation software or not.
* `browser_agent` Browser agent used to make the purchase.
* `vat` Array of VAT details, consists of `amount` in cents and `country` as country code.
# Issue replacement for completed invoice (/docs/api/invoices/issue-replacement-for-completed-invoice)
In the event you want to replace the deliverables of an invoice, this endpoint lets you do so.
When you send a request to the endpoint, behind the scenes a new invoice gets created and immediately marked as completed. From there, the regular flow proceeds with a customer receiving a delivery email with a link to access their products, and you receiving a sales notification.
See the code examples for how to issue a replacement product for an existing invoice with the SellApp API.
## Endpoint
- Method: `PATCH`
- Path: `/v2/invoices/{invoice}/issue-replacement`
- Full URL: `https://sell.app/api/v2/invoices/{invoice}/issue-replacement`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `invoice` (`integer`, required): The invoice path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"product_variants": {
"anyOf": [
{
"type": "integer"
},
{
"type": "array",
"items": {
"type": "integer"
}
}
]
}
},
"required": [
"product_variants"
]
}
```
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"payment": {
"type": "object",
"properties": {
"fee": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"gateway": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"customer_email": {
"type": "string"
},
"transaction_id": {
"type": "string"
}
},
"required": [
"total",
"customer_email",
"transaction_id"
]
},
"type": {
"type": "string"
}
},
"required": [
"data",
"type"
]
},
"subtotal": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"full_price": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"original_amount": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
}
},
"required": [
"fee",
"gateway",
"subtotal",
"expires_at",
"full_price",
"original_amount"
]
},
"status": {
"type": "object",
"properties": {
"history": {
"type": "array",
"items": {
"type": "object",
"properties": {
"setAt": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"setAt",
"status",
"updatedAt"
]
}
},
"status": {
"type": "object",
"properties": {
"setAt": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"setAt",
"status",
"updatedAt"
]
}
},
"required": [
"history",
"status"
]
},
"webhooks": {
"type": "array",
"items": {
"type": "string"
}
},
"feedback": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"coupon_id": {
"type": "null"
},
"subscription_id": {
"type": "null"
},
"customer_information": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"email": {
"type": "string"
},
"country": {
"type": "string"
},
"location": {
"type": "string"
},
"ip": {
"type": "string"
},
"proxied": {
"type": "boolean"
},
"browser_agent": {
"type": "string"
},
"vat": {
"type": "object",
"properties": {
"amount": {
"type": "integer"
},
"country": {
"type": "string"
}
},
"required": [
"amount",
"country"
]
}
},
"required": [
"id",
"email",
"country",
"location",
"ip",
"proxied",
"browser_agent",
"vat"
]
}
},
"required": [
"id",
"payment",
"status",
"webhooks",
"feedback",
"created_at",
"updated_at",
"store_id",
"coupon_id",
"subscription_id",
"customer_information"
]
}
```
Example:
```json
{
"id": 2,
"payment": {
"fee": {
"base": "0",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "0",
"inclusive": "0"
}
},
"gateway": {
"data": {
"total": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"customer_email": "customer@example.com",
"transaction_id": "CQEGF35V"
},
"type": "COINBASE"
},
"subtotal": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"expires_at": "2024-01-10T19:33:12.000000Z",
"full_price": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"original_amount": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
}
},
"status": {
"history": [
{
"setAt": "2024-01-09T19:33:12.000000Z",
"status": "PENDING",
"updatedAt": "2024-01-09T21:17:47.000000Z"
}
],
"status": {
"setAt": "2024-01-09T21:17:47.000000Z",
"status": "COMPLETED",
"updatedAt": "2024-01-09T21:17:47.000000Z"
}
},
"webhooks": [],
"feedback": "",
"created_at": "2024-01-09T19:33:12.000000Z",
"updated_at": "2024-01-09T21:17:47.000000Z",
"store_id": 1,
"coupon_id": null,
"subscription_id": null,
"customer_information": {
"id": 1034,
"email": "customer@example.com",
"country": "Germany",
"location": "Munich",
"ip": "1.3.3.7",
"proxied": false,
"browser_agent": "Mozilla/4.9 (Windows 98; sl-SI; rv:1.9.1.20) Gecko/20110422 Firefox/21.0",
"vat": {
"amount": 0,
"country": "US"
}
}
}
```
# List all invoices (/docs/api/invoices/list-all-invoices)
This endpoint allows you to retrieve a paginated list of all your invoices. By default, a maximum of fifteen invoices are shown per page.
## Endpoint
- Method: `GET`
- Path: `/v2/invoices`
- Full URL: `https://sell.app/api/v2/invoices`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
None.
## Query Parameters
- `limit` (`integer`, optional): Limit the number of blacklist rules returned.
- `page` (`integer`, optional): The page number you are attempting to access.
- `search` (`string`, optional): Free-text search term.
- `search_by` (`string`, optional): Which invoice field the search term should be matched against.
- `id` (`string`, optional): Filter by invoice ID.
- `email` (`string`, optional): Filter by customer email.
- `transaction_id` (`string`, optional): Filter by payment transaction ID.
- `serial_code` (`string`, optional): Filter by delivered serial.
- `additional_info` (`string`, optional): Filter by customer-provided additional information.
- `product_name` (`string`, optional): Filter by product or variant title.
- `discord_data` (`string`, optional): Filter by attached Discord data.
- `crypto_txid` (`string`, optional): Filter by crypto TXID.
- `crypto_address` (`string`, optional): Filter by crypto payment address.
- `coupon_code` (`string`, optional): Filter by coupon code.
- `status` (`array`, optional): Filter by one or more invoice statuses.
- `payment_methods` (`array`, optional): Filter by one or more payment methods.
- `sort` (`string`, optional): Sort order for the result set.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"payment": {
"type": "object",
"properties": {
"fee": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"gateway": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"customer_email": {
"type": "string"
},
"transaction_id": {
"type": "string"
}
},
"required": [
"total",
"customer_email",
"transaction_id"
]
},
"type": {
"type": "string"
}
},
"required": [
"data",
"type"
]
},
"subtotal": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"full_price": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"original_amount": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
}
},
"required": [
"fee",
"gateway",
"subtotal",
"expires_at",
"full_price",
"original_amount"
]
},
"status": {
"type": "object",
"properties": {
"history": {
"type": "array",
"items": {
"type": "object",
"properties": {
"setAt": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"setAt",
"status",
"updatedAt"
]
}
},
"status": {
"type": "object",
"properties": {
"setAt": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"setAt",
"status",
"updatedAt"
]
}
},
"required": [
"history",
"status"
]
},
"webhooks": {
"type": "array",
"items": {
"type": "string"
}
},
"feedback": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"coupon_id": {
"type": "null"
},
"subscription_id": {
"type": "null"
},
"customer_information": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"email": {
"type": "string"
},
"country": {
"type": "string"
},
"location": {
"type": "string"
},
"ip": {
"type": "string"
},
"proxied": {
"type": "boolean"
},
"browser_agent": {
"type": "string"
},
"vat": {
"type": "object",
"properties": {
"amount": {
"type": "integer"
},
"country": {
"type": "string"
}
},
"required": [
"amount",
"country"
]
}
},
"required": [
"id",
"email",
"country",
"location",
"ip",
"proxied",
"browser_agent",
"vat"
]
}
},
"required": [
"id",
"payment",
"status",
"webhooks",
"feedback",
"created_at",
"updated_at",
"store_id",
"coupon_id",
"subscription_id",
"customer_information"
]
}
},
"links": {
"type": "object",
"properties": {}
},
"meta": {
"type": "object",
"properties": {}
}
},
"required": [
"data",
"links",
"meta"
]
}
```
Example:
```json
{
"data": [
{
"id": 1,
"payment": {
"fee": {
"base": "0",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "0",
"inclusive": "0"
}
},
"gateway": {
"data": {
"total": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"customer_email": "customer@example.com",
"transaction_id": "CQEGF35V"
},
"type": "COINBASE"
},
"subtotal": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"expires_at": "2024-01-09T23:50:11.000000Z",
"full_price": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"original_amount": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
}
},
"status": {
"history": [
{
"setAt": "2024-01-09T14:50:11.000000Z",
"status": "PENDING",
"updatedAt": "2024-01-09T18:00:50.000000Z"
}
],
"status": {
"setAt": "2024-01-09T18:00:50.000000Z",
"status": "COMPLETED",
"updatedAt": "2024-01-09T18:00:50.000000Z"
}
},
"webhooks": [],
"feedback": "",
"created_at": "2024-01-09T14:50:11.000000Z",
"updated_at": "2024-01-09T18:00:50.000000Z",
"store_id": 1,
"coupon_id": null,
"subscription_id": null,
"customer_information": {
"id": 123,
"email": "customer@example.com",
"country": "Germany",
"location": "Munich",
"ip": "1.3.3.7",
"proxied": false,
"browser_agent": "Mozilla/4.9 (Windows 98; sl-SI; rv:1.9.1.20) Gecko/20110422 Firefox/21.0",
"vat": {
"amount": 0,
"country": "DE"
}
}
}
],
"links": {},
"meta": {}
}
```
# Mark pending invoice completed (/docs/api/invoices/mark-pending-invoice-completed)
This endpoint allows you to update a pending invoice's status as completed. If marked as completed, the purchased product(s) would be delivered to the customer's email. See the code examples for how to mark a pending invoice as completed with the SellApp API.
The SellApp platform automatically marks invoices as completed once payment has been confirmed.
We advise not using this endpoint unless you are certain you have received the payment and/or there is another reason to mark the invoice as completed manually.
## Endpoint
- Method: `PATCH`
- Path: `/v2/invoices/{invoice}/mark-completed`
- Full URL: `https://sell.app/api/v2/invoices/{invoice}/mark-completed`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `invoice` (`integer`, required): The invoice path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"payment": {
"type": "object",
"properties": {
"fee": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"gateway": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"customer_email": {
"type": "string"
},
"transaction_id": {
"type": "string"
}
},
"required": [
"total",
"customer_email",
"transaction_id"
]
},
"type": {
"type": "string"
}
},
"required": [
"data",
"type"
]
},
"subtotal": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"full_price": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"original_amount": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
}
},
"required": [
"fee",
"gateway",
"subtotal",
"expires_at",
"full_price",
"original_amount"
]
},
"status": {
"type": "object",
"properties": {
"history": {
"type": "array",
"items": {
"type": "object",
"properties": {
"setAt": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"setAt",
"status",
"updatedAt"
]
}
},
"status": {
"type": "object",
"properties": {
"setAt": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"setAt",
"status",
"updatedAt"
]
}
},
"required": [
"history",
"status"
]
},
"webhooks": {
"type": "array",
"items": {
"type": "string"
}
},
"feedback": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"coupon_id": {
"type": "null"
},
"subscription_id": {
"type": "null"
},
"customer_information": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"email": {
"type": "string"
},
"country": {
"type": "string"
},
"location": {
"type": "string"
},
"ip": {
"type": "string"
},
"proxied": {
"type": "boolean"
},
"browser_agent": {
"type": "string"
},
"vat": {
"type": "object",
"properties": {
"amount": {
"type": "integer"
},
"country": {
"type": "string"
}
},
"required": [
"amount",
"country"
]
}
},
"required": [
"id",
"email",
"country",
"location",
"ip",
"proxied",
"browser_agent",
"vat"
]
}
},
"required": [
"id",
"payment",
"status",
"webhooks",
"feedback",
"created_at",
"updated_at",
"store_id",
"coupon_id",
"subscription_id",
"customer_information"
]
}
```
Example:
```json
{
"id": 1,
"payment": {
"fee": {
"base": "0",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "0",
"inclusive": "0"
}
},
"gateway": {
"data": {
"total": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"customer_email": "customer@example.com",
"transaction_id": "CQEGF35V"
},
"type": "COINBASE"
},
"subtotal": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"expires_at": "2024-01-10T19:33:11.000000Z",
"full_price": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"original_amount": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
}
},
"status": {
"history": [
{
"setAt": "2024-01-09T19:33:11.000000Z",
"status": "PENDING",
"updatedAt": "2024-01-09T21:17:46.000000Z"
}
],
"status": {
"setAt": "2024-01-09T21:17:46.000000Z",
"status": "COMPLETED",
"updatedAt": "2024-01-09T21:17:46.000000Z"
}
},
"webhooks": [],
"feedback": "",
"created_at": "2024-01-09T19:33:11.000000Z",
"updated_at": "2024-01-09T21:17:46.000000Z",
"store_id": 1,
"coupon_id": null,
"subscription_id": null,
"customer_information": {
"id": 1034,
"email": "customer@example.com",
"country": "Germany",
"location": "Munich",
"ip": "1.3.3.7",
"proxied": false,
"browser_agent": "Mozilla/4.9 (Windows 98; sl-SI; rv:1.9.1.20) Gecko/20110422 Firefox/21.0",
"vat": {
"amount": 0,
"country": "US"
}
}
}
```
# Mark pending invoice voided (/docs/api/invoices/mark-pending-invoice-voided)
This endpoint allows you to update a pending invoice's status as voided. If marked as voided, the purchased product(s) would not be delivered to the customer's email. See the code examples for how to mark a pending invoice as voided with the SellApp API.
## Endpoint
- Method: `PATCH`
- Path: `/v2/invoices/{invoice}/mark-voided`
- Full URL: `https://sell.app/api/v2/invoices/{invoice}/mark-voided`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `invoice` (`integer`, required): The invoice path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"payment": {
"type": "object",
"properties": {
"fee": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"gateway": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"customer_email": {
"type": "string"
},
"transaction_id": {
"type": "string"
}
},
"required": [
"total",
"customer_email",
"transaction_id"
]
},
"type": {
"type": "string"
}
},
"required": [
"data",
"type"
]
},
"subtotal": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"full_price": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"original_amount": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
}
},
"required": [
"fee",
"gateway",
"subtotal",
"expires_at",
"full_price",
"original_amount"
]
},
"status": {
"type": "object",
"properties": {
"history": {
"type": "array",
"items": {
"type": "object",
"properties": {
"setAt": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"setAt",
"status",
"updatedAt"
]
}
},
"status": {
"type": "object",
"properties": {
"setAt": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"setAt",
"status",
"updatedAt"
]
}
},
"required": [
"history",
"status"
]
},
"webhooks": {
"type": "array",
"items": {
"type": "string"
}
},
"feedback": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"coupon_id": {
"type": "null"
},
"subscription_id": {
"type": "null"
},
"customer_information": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"email": {
"type": "string"
},
"country": {
"type": "string"
},
"location": {
"type": "string"
},
"ip": {
"type": "string"
},
"proxied": {
"type": "boolean"
},
"browser_agent": {
"type": "string"
},
"vat": {
"type": "object",
"properties": {
"amount": {
"type": "integer"
},
"country": {
"type": "string"
}
},
"required": [
"amount",
"country"
]
}
},
"required": [
"id",
"email",
"country",
"location",
"ip",
"proxied",
"browser_agent",
"vat"
]
}
},
"required": [
"id",
"payment",
"status",
"webhooks",
"feedback",
"created_at",
"updated_at",
"store_id",
"coupon_id",
"subscription_id",
"customer_information"
]
}
```
Example:
```json
{
"id": 1,
"payment": {
"fee": {
"base": "0",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "0",
"inclusive": "0"
}
},
"gateway": {
"data": {
"total": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"customer_email": "customer@example.com",
"transaction_id": "CQEGF35V"
},
"type": "COINBASE"
},
"subtotal": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"expires_at": "2024-01-10T19:33:11.000000Z",
"full_price": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"original_amount": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
}
},
"status": {
"history": [
{
"setAt": "2024-01-09T19:33:11.000000Z",
"status": "PENDING",
"updatedAt": "2024-01-09T21:17:46.000000Z"
}
],
"status": {
"setAt": "2024-01-09T21:17:46.000000Z",
"status": "VOIDED",
"updatedAt": "2024-01-09T21:17:46.000000Z"
}
},
"webhooks": [],
"feedback": "",
"created_at": "2024-01-09T19:33:11.000000Z",
"updated_at": "2024-01-09T21:17:46.000000Z",
"store_id": 1,
"coupon_id": null,
"subscription_id": null,
"customer_information": {
"id": 1034,
"email": "customer@example.com",
"country": "Germany",
"location": "Munich",
"ip": "1.3.3.7",
"proxied": false,
"browser_agent": "Mozilla/4.9 (Windows 98; sl-SI; rv:1.9.1.20) Gecko/20110422 Firefox/21.0",
"vat": {
"amount": 0,
"country": "US"
}
}
}
```
# Retrieve an invoice (/docs/api/invoices/retrieve-an-invoice)
You can retrieve a specific invoice using this endpoint. By providing the unique identifier, the specific invoice's details will be returned.
Refer to [the list](/api/invoices#the-invoice-model) to see which properties are included with invoice objects.
## Endpoint
- Method: `GET`
- Path: `/v2/invoices/{invoice}`
- Full URL: `https://sell.app/api/v2/invoices/{invoice}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `invoice` (`integer`, required): The invoice path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"payment": {
"type": "object",
"properties": {
"fee": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"gateway": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"total": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"customer_email": {
"type": "string"
},
"transaction_id": {
"type": "string"
}
},
"required": [
"total",
"customer_email",
"transaction_id"
]
},
"type": {
"type": "string"
}
},
"required": [
"data",
"type"
]
},
"subtotal": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"full_price": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
},
"original_amount": {
"type": "object",
"properties": {
"base": {
"type": "string"
},
"currency": {
"type": "string"
},
"units": {
"type": "integer"
},
"vat": {
"type": "integer"
},
"total": {
"type": "object",
"properties": {
"exclusive": {
"type": "string"
},
"inclusive": {
"type": "string"
}
},
"required": [
"exclusive",
"inclusive"
]
}
},
"required": [
"base",
"currency",
"units",
"vat",
"total"
]
}
},
"required": [
"fee",
"gateway",
"subtotal",
"expires_at",
"full_price",
"original_amount"
]
},
"status": {
"type": "object",
"properties": {
"history": {
"type": "array",
"items": {
"type": "object",
"properties": {
"setAt": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"setAt",
"status",
"updatedAt"
]
}
},
"status": {
"type": "object",
"properties": {
"setAt": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string"
},
"updatedAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"setAt",
"status",
"updatedAt"
]
}
},
"required": [
"history",
"status"
]
},
"webhooks": {
"type": "array",
"items": {
"type": "string"
}
},
"feedback": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"coupon_id": {
"type": "null"
},
"subscription_id": {
"type": "null"
},
"customer_information": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"email": {
"type": "string"
},
"country": {
"type": "string"
},
"location": {
"type": "string"
},
"ip": {
"type": "string"
},
"proxied": {
"type": "boolean"
},
"browser_agent": {
"type": "string"
},
"vat": {
"type": "object",
"properties": {
"amount": {
"type": "integer"
},
"country": {
"type": "string"
}
},
"required": [
"amount",
"country"
]
}
},
"required": [
"id",
"email",
"country",
"location",
"ip",
"proxied",
"browser_agent",
"vat"
]
}
},
"required": [
"id",
"payment",
"status",
"webhooks",
"feedback",
"created_at",
"updated_at",
"store_id",
"coupon_id",
"subscription_id",
"customer_information"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 1,
"payment": {
"fee": {
"base": "0",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "0",
"inclusive": "0"
}
},
"gateway": {
"data": {
"total": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"customer_email": "customer@example.com",
"transaction_id": "CQEGF35V"
},
"type": "COINBASE"
},
"subtotal": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"expires_at": "2024-01-09T23:50:11.000000Z",
"full_price": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
},
"original_amount": {
"base": "1999",
"currency": "USD",
"units": 1,
"vat": 0,
"total": {
"exclusive": "1999",
"inclusive": "1999"
}
}
},
"status": {
"history": [
{
"setAt": "2024-01-09T14:50:11.000000Z",
"status": "PENDING",
"updatedAt": "2024-01-09T18:00:50.000000Z"
}
],
"status": {
"setAt": "2024-01-09T18:00:50.000000Z",
"status": "COMPLETED",
"updatedAt": "2024-01-09T18:00:50.000000Z"
}
},
"webhooks": [],
"feedback": "",
"created_at": "2024-01-09T14:50:11.000000Z",
"updated_at": "2024-01-09T18:00:50.000000Z",
"store_id": 1,
"coupon_id": null,
"subscription_id": null,
"customer_information": {
"id": 123,
"email": "customer@example.com",
"country": "Germany",
"location": "Munich",
"ip": "1.3.3.7",
"proxied": false,
"browser_agent": "Mozilla/4.9 (Windows 98; sl-SI; rv:1.9.1.20) Gecko/20110422 Firefox/21.0",
"vat": {
"amount": 0,
"country": "DE"
}
}
}
}
```
# Search invoices (/docs/api/invoices/search-invoices)
This endpoint is a backward-compatible search endpoint for invoice lookups. It accepts the same filters as the list endpoint, but in a JSON request body instead of query parameters.
## Endpoint
- Method: `POST`
- Path: `/v2/invoices/search`
- Full URL: `https://sell.app/api/v2/invoices/search`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
None.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"search": {
"type": "string"
},
"search_by": {
"type": "string",
"enum": [
"default",
"transaction_id",
"serial_code",
"additional_info",
"product_name",
"discord_data",
"crypto_txid",
"crypto_address",
"coupon_code"
]
},
"id": {
"type": "string"
},
"email": {
"type": "string"
},
"transaction_id": {
"type": "string"
},
"serial_code": {
"type": "string"
},
"additional_info": {
"type": "string"
},
"product_name": {
"type": "string"
},
"discord_data": {
"type": "string"
},
"crypto_txid": {
"type": "string"
},
"crypto_address": {
"type": "string"
},
"coupon_code": {
"type": "string"
},
"status": {
"type": "array",
"items": {
"type": "string",
"enum": [
"PENDING",
"REVERSED",
"PARTIAL",
"VOIDED",
"REFUNDED",
"PAID",
"COMPLETED",
"DISPUTING",
"REVIEW",
"FAILED"
]
}
},
"payment_methods": {
"type": "array",
"items": {
"type": "string",
"enum": [
"AUTHNET",
"BTCPAY",
"CASHAPP",
"COINBASE",
"PADDLE",
"PAYDASH",
"PAYPAL",
"PAYSTACK",
"SQUARE",
"STRIPE",
"VENMO",
"NMI",
"LIFI",
"BTC",
"LTC",
"ETH",
"XMR",
"SOL",
"ADA",
"BNB",
"TRX",
"MATIC",
"ETH_USDT",
"ETH_USDC",
"ETH_UNI",
"ETH_SHIB",
"ETH_DAI",
"BNB_USDT",
"BNB_USDC",
"TRX_USDT",
"TRX_USDC",
"SOL_USDT",
"SOL_USDC"
]
}
},
"sort": {
"type": "string",
"enum": [
"created_at",
"-created_at"
]
}
}
}
```
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
}
},
"required": [
"id"
]
}
},
"links": {
"type": "object",
"properties": {}
},
"meta": {
"type": "object",
"properties": {}
}
},
"required": [
"data",
"links",
"meta"
]
}
```
Example:
```json
{
"data": [
{
"id": 1
}
],
"links": {},
"meta": {}
}
```
# View invoice deliverables (/docs/api/invoices/view-invoice-deliverables)
This endpoint shows the deliverables that have been sent to the customer. If a customer has purchased multiple products, all of the deliverables will be shown.
See the code examples for how to display the deliverables for an existing invoice with the SellApp API.
## Endpoint
- Method: `GET`
- Path: `/v2/invoices/{invoice}/deliverables`
- Full URL: `https://sell.app/api/v2/invoices/{invoice}/deliverables`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `invoice` (`integer`, required): The invoice path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"invoice_id": {
"type": "integer"
},
"product_variant_id": {
"type": "integer"
},
"deliverable": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"serials": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"serials"
]
},
"types": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"data",
"types"
]
}
},
"required": [
"invoice_id",
"product_variant_id",
"deliverable"
]
}
```
Example:
```json
{
"invoice_id": 1,
"product_variant_id": 1,
"deliverable": {
"data": {
"serials": [
"YOUR-KEY-HERE-THANKS"
]
},
"types": [
"TEXT"
]
}
}
```
# Activate a license key (/docs/api/licenses/activate-a-license-key)
This endpoint activates a given license key and creates an instance of the license key. Activation registers a unique identifier (instance name) against the license key. If the activation is successful, it returns the details of the newly created `LicenseKeyInstance`, including its unique `id` which should be stored by the client/application for future validation.
Activation can fail if:
* The license key does not exist.
* The license key is inactive (`active` is false).
* The license key has expired (`expires_at` is in the past).
* The activation limit (`limit`) has been reached.
## Endpoint
- Method: `POST`
- Path: `/v2/licenses/activate`
- Full URL: `https://sell.app/api/v2/licenses/activate`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
None.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"license_key": {
"type": "string"
},
"instance_name": {
"type": "string"
}
},
"required": [
"license_key",
"instance_name"
]
}
```
Example:
```json
{
"license_key": "01965f1d-f038-7116-b57f-9e7ecb4e7b8f",
"instance_name": "zezima@osrs.com"
}
```
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"license_key_id": {
"type": "integer"
},
"name": {
"type": "string"
},
"store_id": {
"type": "integer"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"license_key_id",
"name",
"store_id",
"created_at",
"updated_at"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": "9ebd37af-2077-42f9-9f88-d96cfc6ef1a8",
"license_key_id": 1,
"name": "zezima@osrs.com",
"store_id": 1,
"created_at": "2025-04-22T20:53:22.000000Z",
"updated_at": "2025-04-22T20:53:22.000000Z"
}
}
```
# Overview (/docs/api/licenses)
The Licenses API endpoints helps you manage licenses purchased through your store.
[License instances](/api/license-instances) are part of a license key. Each
license key can be linked to multiple instances. Whenever you activate a
license key, you create a new instance of the license key.
## Endpoints [#endpoints]
* [Activate a license key](/api/licenses/activate-a-license-key)
* [Validate a license key](/api/licenses/validate-a-license-key)
* [List all license keys](/api/licenses/list-all-license-keys)
* [Retrieve a license key](/api/licenses/retrieve-a-license-key)
* [Update a license key](/api/licenses/update-a-license-key)
## The license key model [#the-license-key-model]
The license key model represents a single license key purchased by a customer.
### Properties [#properties]
*(read-only)* The unique identifier for the license key.
*(read-only)* The actual license key string
The maximum number of instances this key can be activated on. `null` means unlimited activations.
Whether the license key is currently active which you can modify via the API and which is unrelated to the status. Inactive keys cannot be activated or validated successfully.
*(read-only)* The status of the license key, one of: `ACTIVE`, `INACTIVE`, `EXPIRED`
The timestamp when the license key expires. `null` means the license will never expire.
Whether the license key is expired.
*(read-only)* The ID of the store this license key belongs to.
*(read-only)* The ID of the order associated with this license key.
*(read-only)* The ID of the associated invoice V2, if applicable.
*(read-only)* The ID of the product this license is for.
*(read-only)* The ID of the specific product variant this license is for.
*(read-only)* The ID of the customer that purchased this license key.
*(read-only)* The ID of the associated subscription, if applicable.
*(read-only)* Time at which the license key was created.
*(read-only)* Time at which the license key was last updated.
## The license instance model [#the-license-instance-model]
The license instance model represents a single activation of a license key on a specific device or identifier.
### Properties [#properties-1]
*(read-only)* The unique identifier (UUID) of the license instance. **This is the `instance_id` used for validation.**
*(read-only)* The unique identifier for the parent license key which this instance is linked to.
*(read-only)* The name provided during activation, which you can use to identify this instance (e.g., the customer's email or HWID).
*(read-only)* The ID of the store this instance belongs to.
*(read-only)* Time at which the instance was created (activation time).
*(read-only)* Time at which the instance was last updated.
***
# List all license keys (/docs/api/licenses/list-all-license-keys)
Retrieves a paginated list of all license keys associated with your store. Standard pagination parameters (`limit`, `page`) can be used.
Refer to [the license key model](#the-license-key-model) section for details on the returned object structure.
### Optional Query Parameters [#optional-query-parameters]
Limit the number of license keys returned per page.
The page number to retrieve.
## Endpoint
- Method: `GET`
- Path: `/v2/license-keys`
- Full URL: `https://sell.app/api/v2/license-keys`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
None.
## Query Parameters
- `limit` (`integer`, optional): Limit the number of blacklist rules returned.
- `page` (`integer`, optional): The page number you are attempting to access.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"key": {
"type": "string"
},
"limit": {
"type": "integer"
},
"active": {
"type": "integer"
},
"status": {
"type": "string"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"is_expired": {
"type": "integer"
},
"store_id": {
"type": "integer"
},
"order_id": {
"type": "integer"
},
"invoice_id": {
"type": "integer"
},
"product_id": {
"type": "integer"
},
"variant_id": {
"type": "integer"
},
"customer_id": {
"type": "integer"
},
"subscription_id": {
"type": "null"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"key",
"limit",
"active",
"status",
"expires_at",
"is_expired",
"store_id",
"order_id",
"invoice_id",
"product_id",
"variant_id",
"customer_id",
"subscription_id",
"created_at",
"updated_at"
]
}
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": [
{
"id": 1,
"key": "01965f1d-f038-7116-b57f-9e7ecb4e7b8f",
"limit": 4,
"active": 1,
"status": "ACTIVE",
"expires_at": "2025-05-22T20:08:39.000000Z",
"is_expired": 0,
"store_id": 1,
"order_id": 1,
"invoice_id": 1,
"product_id": 1,
"variant_id": 1,
"customer_id": 1,
"subscription_id": null,
"created_at": "2025-04-22T20:08:39.000000Z",
"updated_at": "2025-04-22T20:08:39.000000Z"
}
]
}
```
# Retrieve a license key (/docs/api/licenses/retrieve-a-license-key)
Retrieves the details of a specific license key by its unique ID (not key!)
Refer to [the license key model](../licenses#the-license-instance-model) section for details on the returned object structure.
## Endpoint
- Method: `GET`
- Path: `/v2/license-keys/{license_key}`
- Full URL: `https://sell.app/api/v2/license-keys/{license_key}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `license_key` (`integer`, required): The license key path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"key": {
"type": "string"
},
"limit": {
"type": "integer"
},
"active": {
"type": "integer"
},
"status": {
"type": "string"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"is_expired": {
"type": "integer"
},
"store_id": {
"type": "integer"
},
"order_id": {
"type": "integer"
},
"invoice_id": {
"type": "integer"
},
"product_id": {
"type": "integer"
},
"variant_id": {
"type": "integer"
},
"customer_id": {
"type": "integer"
},
"subscription_id": {
"type": "null"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"key",
"limit",
"active",
"status",
"expires_at",
"is_expired",
"store_id",
"order_id",
"invoice_id",
"product_id",
"variant_id",
"customer_id",
"subscription_id",
"created_at",
"updated_at"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 1,
"key": "01965f1d-f038-7116-b57f-9e7ecb4e7b8f",
"limit": 4,
"active": 1,
"status": "ACTIVE",
"expires_at": "2025-05-22T20:08:39.000000Z",
"is_expired": 0,
"store_id": 1,
"order_id": 1,
"invoice_id": 1,
"product_id": 1,
"variant_id": 1,
"customer_id": 1,
"subscription_id": null,
"created_at": "2025-04-22T20:08:39.000000Z",
"updated_at": "2025-04-22T20:08:39.000000Z"
}
}
```
# Update a license key (/docs/api/licenses/update-a-license-key)
Updates specific properties of a license key. You can modify the activation limit, expiration date, and active status.
If you decrease the `limit` to a value lower than the current `instances_count`, the oldest instances will be automatically deleted to match the new limit.
## Endpoint
- Method: `PATCH`
- Path: `/v2/license-keys/{license_key}`
- Full URL: `https://sell.app/api/v2/license-keys/{license_key}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `license_key` (`integer`, required): The license key path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"limit": {
"type": [
"integer",
"null"
]
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"active": {
"type": [
"boolean",
"null"
]
}
}
}
```
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"key": {
"type": "string"
},
"limit": {
"type": "integer"
},
"active": {
"type": "integer"
},
"status": {
"type": "string"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"is_expired": {
"type": "integer"
},
"store_id": {
"type": "integer"
},
"order_id": {
"type": "integer"
},
"invoice_id": {
"type": "integer"
},
"product_id": {
"type": "integer"
},
"variant_id": {
"type": "integer"
},
"customer_id": {
"type": "integer"
},
"subscription_id": {
"type": "null"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"instances_count": {
"type": "integer"
}
},
"required": [
"id",
"key",
"limit",
"active",
"status",
"expires_at",
"is_expired",
"store_id",
"order_id",
"invoice_id",
"product_id",
"variant_id",
"customer_id",
"subscription_id",
"created_at",
"updated_at",
"instances_count"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 1,
"key": "01965f1d-f038-7116-b57f-9e7ecb4e7b8f",
"limit": 10,
"active": 0,
"status": "ACTIVE",
"expires_at": "2025-05-03T20:00:00.000000Z",
"is_expired": 0,
"store_id": 1,
"order_id": 1,
"invoice_id": 1,
"product_id": 1,
"variant_id": 1,
"customer_id": 1,
"subscription_id": null,
"created_at": "2025-04-22T20:08:39.000000Z",
"updated_at": "2025-04-22T21:20:51.000000Z",
"instances_count": 4
}
}
```
# Validate a license key (/docs/api/licenses/validate-a-license-key)
Checks if a given license key and instance ID pair represents a valid, active license activation. This is the primary endpoint to use within your application to verify a user's license status periodically.
Validation checks if:
* The license key exists.
* The license key is currently `active`.
* The license key has not expired (`expires_at`).
* The provided `instance_id` matches an existing activation for that license key.
## Endpoint
- Method: `POST`
- Path: `/v2/licenses/validate`
- Full URL: `https://sell.app/api/v2/licenses/validate`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
None.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"license_key": {
"type": "string"
},
"instance_id": {
"type": "string"
}
},
"required": [
"license_key"
]
}
```
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"valid": {
"type": "boolean"
},
"license_key": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"key": {
"type": "string"
},
"limit": {
"type": "integer"
},
"active": {
"type": "integer"
},
"status": {
"type": "string"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"is_expired": {
"type": "integer"
},
"store_id": {
"type": "integer"
},
"order_id": {
"type": "integer"
},
"invoice_id": {
"type": "integer"
},
"product_id": {
"type": "integer"
},
"variant_id": {
"type": "integer"
},
"customer_id": {
"type": "integer"
},
"subscription_id": {
"type": "null"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"instances_count": {
"type": "integer"
}
},
"required": [
"id",
"key",
"limit",
"active",
"status",
"expires_at",
"is_expired",
"store_id",
"order_id",
"invoice_id",
"product_id",
"variant_id",
"customer_id",
"subscription_id",
"created_at",
"updated_at",
"instances_count"
]
},
"instance": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"license_key_id": {
"type": "integer"
},
"name": {
"type": "string"
},
"store_id": {
"type": "integer"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"license_key_id",
"name",
"store_id",
"created_at",
"updated_at"
]
}
},
"required": [
"valid",
"license_key",
"instance"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"valid": true,
"license_key": {
"id": 1,
"key": "01965f1d-f038-7116-b57f-9e7ecb4e7b8f",
"limit": 4,
"active": 1,
"status": "ACTIVE",
"expires_at": "2025-05-22T20:08:39.000000Z",
"is_expired": 0,
"store_id": 1,
"order_id": 1,
"invoice_id": 1,
"product_id": 218,
"variant_id": 228,
"customer_id": 1,
"subscription_id": null,
"created_at": "2025-04-22T20:08:39.000000Z",
"updated_at": "2025-04-22T20:08:39.000000Z",
"instances_count": 4
},
"instance": {
"id": "9ebd3be0-de72-4da7-805e-bc99d1ac1186",
"license_key_id": 1,
"name": "zezima@osrs.com",
"store_id": 1,
"created_at": "2025-04-22T21:05:06.000000Z",
"updated_at": "2025-04-22T21:05:06.000000Z"
}
}
}
```
# Create a product variant (/docs/api/product-variants/create-a-product-variant)
This endpoint allows you to create a new product variant. See the code examples for how to create a new product variant with the SellApp API.
## Endpoint
- Method: `POST`
- Path: `/v2/products/{product}/variants`
- Full URL: `https://sell.app/api/v2/products/{product}/variants`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `product` (`integer`, required): The product path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"deliverable": {
"type": "object",
"properties": {
"types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"DOWNLOADABLE",
"TEXT",
"DYNAMIC",
"MANUAL",
"LICENSE_KEY",
"BUNDLE"
]
}
},
"data": {
"type": "object",
"properties": {
"stock": {
"type": [
"integer",
"null"
]
},
"serials": {
"type": "array",
"items": {
"type": "string"
}
},
"removeDuplicate": {
"type": "boolean"
},
"parsingMode": {
"type": "string",
"enum": [
"COMMA",
"NEW_LINE",
"SPACE",
"CUSTOM"
]
},
"comment": {
"type": "string"
},
"webhook": {
"type": "string",
"format": "uri"
}
}
}
},
"required": [
"types",
"data"
]
},
"pricing": {
"type": "object",
"properties": {
"humble": {
"type": "boolean"
},
"price": {
"type": "object",
"properties": {
"price": {
"type": "integer"
},
"currency": {
"type": "string"
}
},
"required": [
"price",
"currency"
]
}
},
"required": [
"humble",
"price"
]
},
"minimum_purchase_quantity": {
"type": "integer"
},
"maximum_purchase_quantity": {
"type": [
"integer",
"null"
]
},
"bulk_discount": {
"type": "array",
"items": {
"type": "object",
"properties": {
"minimum_purchase_amount": {
"type": "integer"
},
"discount_percentage": {
"type": "integer"
}
},
"required": [
"minimum_purchase_amount",
"discount_percentage"
]
}
},
"payment_methods": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"enum": [
"AUTHNET",
"BTCPAY",
"CASHAPP",
"COINBASE",
"PADDLE",
"PAYDASH",
"PAYPAL",
"PAYSTACK",
"SQUARE",
"STRIPE",
"VENMO",
"NMI",
"LIFI",
"BTC",
"LTC",
"ETH",
"XMR",
"SOL",
"ADA",
"BNB",
"TRX",
"MATIC",
"ETH_USDT",
"ETH_USDC",
"ETH_UNI",
"ETH_SHIB",
"ETH_DAI",
"BNB_USDT",
"BNB_USDC",
"TRX_USDT",
"TRX_USDC",
"SOL_USDT",
"SOL_USDC"
]
}
},
"other_settings": {
"type": "object",
"properties": {
"quantity_increments": {
"type": "integer"
}
}
}
},
"required": [
"title",
"description",
"deliverable",
"pricing",
"payment_methods"
]
}
```
### Content Type: `multipart/form-data`
Schema:
```json
{
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"deliverable": {
"type": "object",
"properties": {
"types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"DOWNLOADABLE",
"TEXT",
"DYNAMIC",
"MANUAL",
"LICENSE_KEY",
"BUNDLE"
]
}
},
"data": {
"type": "object",
"properties": {
"stock": {
"type": [
"integer",
"null"
]
},
"serials": {
"type": "array",
"items": {
"type": "string"
}
},
"removeDuplicate": {
"type": "boolean"
},
"parsingMode": {
"type": "string",
"enum": [
"COMMA",
"NEW_LINE",
"SPACE",
"CUSTOM"
]
},
"comment": {
"type": "string"
},
"webhook": {
"type": "string",
"format": "uri"
},
"file": {
"type": "string",
"format": "binary"
},
"files": {
"type": "array",
"items": {
"type": "string",
"format": "binary"
}
}
}
}
},
"required": [
"types",
"data"
]
},
"pricing": {
"type": "object",
"properties": {
"humble": {
"type": "boolean"
},
"price": {
"type": "object",
"properties": {
"price": {
"type": "integer"
},
"currency": {
"type": "string"
}
},
"required": [
"price",
"currency"
]
}
},
"required": [
"humble",
"price"
]
},
"minimum_purchase_quantity": {
"type": "integer"
},
"maximum_purchase_quantity": {
"type": [
"integer",
"null"
]
},
"bulk_discount": {
"type": "array",
"items": {
"type": "object",
"properties": {
"minimum_purchase_amount": {
"type": "integer"
},
"discount_percentage": {
"type": "integer"
}
},
"required": [
"minimum_purchase_amount",
"discount_percentage"
]
}
},
"payment_methods": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"enum": [
"AUTHNET",
"BTCPAY",
"CASHAPP",
"COINBASE",
"PADDLE",
"PAYDASH",
"PAYPAL",
"PAYSTACK",
"SQUARE",
"STRIPE",
"VENMO",
"NMI",
"LIFI",
"BTC",
"LTC",
"ETH",
"XMR",
"SOL",
"ADA",
"BNB",
"TRX",
"MATIC",
"ETH_USDT",
"ETH_USDC",
"ETH_UNI",
"ETH_SHIB",
"ETH_DAI",
"BNB_USDT",
"BNB_USDC",
"TRX_USDT",
"TRX_USDC",
"SOL_USDT",
"SOL_USDC"
]
}
},
"other_settings": {
"type": "object",
"properties": {
"quantity_increments": {
"type": "integer"
}
}
}
},
"required": [
"title",
"description",
"deliverable",
"pricing",
"payment_methods"
]
}
```
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"product_id": {
"type": "integer"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"deliverable": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"removeDuplicate": {
"type": "boolean"
},
"parsingMode": {
"type": "string"
},
"stock": {
"type": "integer"
},
"comment": {
"type": "string"
},
"serials": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"removeDuplicate",
"parsingMode",
"stock",
"comment",
"serials"
]
},
"types": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"data",
"types"
]
},
"pricing": {
"type": "object",
"properties": {
"humble": {
"type": "boolean"
},
"frequency": {
"type": "object",
"properties": {
"value": {
"type": "integer"
},
"interval": {
"type": "string"
}
},
"required": [
"value",
"interval"
]
},
"type": {
"type": "string"
},
"price": {
"type": "object",
"properties": {
"price": {
"type": "string"
},
"currency": {
"type": "string"
}
},
"required": [
"price",
"currency"
]
}
},
"required": [
"humble",
"frequency",
"type",
"price"
]
},
"minimum_purchase_quantity": {
"type": "integer"
},
"maximum_purchase_quantity": {
"type": "integer"
},
"bulk_discount": {
"type": "array",
"items": {
"type": "object",
"properties": {
"discount_percentage": {
"type": "integer"
},
"minimum_purchase_amount": {
"type": "integer"
}
},
"required": [
"discount_percentage",
"minimum_purchase_amount"
]
}
},
"payment_methods": {
"type": "array",
"items": {
"type": "string"
}
},
"other_settings": {
"type": "object",
"properties": {
"quantity_increments": {
"type": "integer"
},
"discord_data_required": {
"type": "boolean"
}
},
"required": [
"quantity_increments",
"discord_data_required"
]
},
"order": {
"type": "integer"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"deleted_at": {
"type": "null"
},
"product": {
"type": "object",
"properties": {
"additional_information": {
"type": "array",
"items": {
"type": "object",
"properties": {
"required": {
"type": "boolean"
},
"key": {
"type": "string"
},
"type": {
"type": "string"
},
"label": {
"type": "string"
}
},
"required": [
"required",
"key",
"type",
"label"
]
}
}
},
"required": [
"additional_information"
]
}
},
"required": [
"id",
"product_id",
"title",
"description",
"deliverable",
"pricing",
"minimum_purchase_quantity",
"maximum_purchase_quantity",
"bulk_discount",
"payment_methods",
"other_settings",
"order",
"created_at",
"updated_at",
"deleted_at",
"product"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 2,
"product_id": 1,
"title": "Variant Title",
"description": "Variant Description",
"deliverable": {
"data": {
"removeDuplicate": false,
"parsingMode": "COMMA",
"stock": 3,
"comment": "Thanks for the purchase! I will send you a contract by email. Make sure to sign it with your blood.",
"serials": [
"1",
"2",
"3"
]
},
"types": [
"TEXT",
"MANUAL"
]
},
"pricing": {
"humble": true,
"frequency": {
"value": 1,
"interval": "MONTH"
},
"type": "SINGLE_PAYMENT",
"price": {
"price": "1999",
"currency": "USD"
}
},
"minimum_purchase_quantity": 1,
"maximum_purchase_quantity": 3,
"bulk_discount": [
{
"discount_percentage": 10,
"minimum_purchase_amount": 10
}
],
"payment_methods": [
"BTC",
"STRIPE"
],
"other_settings": {
"quantity_increments": 2,
"discord_data_required": false
},
"order": 1,
"created_at": "2024-01-10T18:47:22.000000Z",
"updated_at": "2024-01-10T18:47:22.000000Z",
"deleted_at": null,
"product": {
"additional_information": [
{
"required": true,
"key": "5ebae238c0afae7f4a4b96b30ff6f34c",
"type": "CHECKBOX",
"label": "I agree to handing over my soul"
}
]
}
}
}
```
# Delete a product variant (/docs/api/product-variants/delete-a-product-variant)
This endpoint allows you to delete a product variant.
This will permanently delete the product variant and all of its details, including the sensitive deliverables, will no longer be retrievable.
## Endpoint
- Method: `DELETE`
- Path: `/v2/products/{product}/variants/{variant}`
- Full URL: `https://sell.app/api/v2/products/{product}/variants/{variant}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `product` (`integer`, required): The product path parameter.
- `variant` (`integer`, required): The variant path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"product_id": {
"type": "integer"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"deliverable": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"removeDuplicate": {
"type": "boolean"
},
"parsingMode": {
"type": "string"
},
"stock": {
"type": "integer"
},
"comment": {
"type": "string"
},
"serials": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"removeDuplicate",
"parsingMode",
"stock",
"comment",
"serials"
]
},
"types": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"data",
"types"
]
},
"pricing": {
"type": "object",
"properties": {
"humble": {
"type": "boolean"
},
"frequency": {
"type": "object",
"properties": {
"value": {
"type": "integer"
},
"interval": {
"type": "string"
}
},
"required": [
"value",
"interval"
]
},
"type": {
"type": "string"
},
"price": {
"type": "object",
"properties": {
"price": {
"type": "string"
},
"currency": {
"type": "string"
}
},
"required": [
"price",
"currency"
]
}
},
"required": [
"humble",
"frequency",
"type",
"price"
]
},
"minimum_purchase_quantity": {
"type": "integer"
},
"maximum_purchase_quantity": {
"type": "integer"
},
"bulk_discount": {
"type": "array",
"items": {
"type": "object",
"properties": {
"discount_percentage": {
"type": "integer"
},
"minimum_purchase_amount": {
"type": "integer"
}
},
"required": [
"discount_percentage",
"minimum_purchase_amount"
]
}
},
"payment_methods": {
"type": "array",
"items": {
"type": "string"
}
},
"other_settings": {
"type": "object",
"properties": {
"quantity_increments": {
"type": "integer"
},
"discord_data_required": {
"type": "boolean"
}
},
"required": [
"quantity_increments",
"discord_data_required"
]
},
"order": {
"type": "integer"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"deleted_at": {
"type": "null"
},
"product": {
"type": "object",
"properties": {
"additional_information": {
"type": "array",
"items": {
"type": "object",
"properties": {
"required": {
"type": "boolean"
},
"key": {
"type": "string"
},
"type": {
"type": "string"
},
"label": {
"type": "string"
}
},
"required": [
"required",
"key",
"type",
"label"
]
}
}
},
"required": [
"additional_information"
]
}
},
"required": [
"id",
"product_id",
"title",
"description",
"deliverable",
"pricing",
"minimum_purchase_quantity",
"maximum_purchase_quantity",
"bulk_discount",
"payment_methods",
"other_settings",
"order",
"created_at",
"updated_at",
"deleted_at",
"product"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 2,
"product_id": 1,
"title": "Variant Title",
"description": "Variant Description",
"deliverable": {
"data": {
"removeDuplicate": false,
"parsingMode": "COMMA",
"stock": 3,
"comment": "Thanks for the purchase! I'll send you a contract by email. Make sure to sign it with your blood.",
"serials": [
"1",
"2",
"3"
]
},
"types": [
"TEXT",
"MANUAL"
]
},
"pricing": {
"humble": true,
"frequency": {
"value": 1,
"interval": "MONTH"
},
"type": "SINGLE_PAYMENT",
"price": {
"price": "1999",
"currency": "USD"
}
},
"minimum_purchase_quantity": 1,
"maximum_purchase_quantity": 3,
"bulk_discount": [
{
"discount_percentage": 10,
"minimum_purchase_amount": 10
}
],
"payment_methods": [
"BTC",
"STRIPE"
],
"other_settings": {
"quantity_increments": 2,
"discord_data_required": false
},
"order": 1,
"created_at": "2024-01-10T18:47:22.000000Z",
"updated_at": "2024-01-10T18:47:22.000000Z",
"deleted_at": null,
"product": {
"additional_information": [
{
"required": true,
"key": "5ebae238c0afae7f4a4b96b30ff6f34c",
"type": "CHECKBOX",
"label": "I agree to handing over my soul"
}
]
}
}
}
```
# Overview (/docs/api/product-variants)
Product variants are intertwined with products. It's what contains all data pertaining to deliverables and pricing.
As you might have already noticed, one product is able to have multiple variants which each can have their unique deliverables and pricing.
On this page, we'll dive into the different product variant endpoints you can use to manage products programmatically. We'll look at how to create, update, and delete product variants.
## Endpoints [#endpoints]
* [List all product variants](/api/product-variants/list-all-product-variants)
* [Create a product variant](/api/product-variants/create-a-product-variant)
* [Retrieve a product variant](/api/product-variants/retrieve-a-product-variant)
* [Update a product variant](/api/product-variants/update-a-product-variant)
* [Delete a product variant](/api/product-variants/delete-a-product-variant)
## The product variant model [#the-product-variant-model]
The product variant model contains all the information about the product variants located within a product, including the price and deliverables.
### Properties [#properties]
The unique identifier for the product.
The unique product identified this variant is linked to.
The product variant title.
The product variant description.
Deliverable details of the product variant, consists of the following:
* `data` Array of deliverable data to be delivered. Consists of the following:
* `serials` Only applicable if `deliverable.types` contains `TEXT`. This array should contain all of your serials, separated by the delimiter you set in `parsingMode`.
* `removeDuplicate` Whether duplicate `TEXT` values should be removed.
* `parsingMode` In which way `TEXT` values are separated/parsed.
* `comment` Only applicable if `deliverable.types` contains `MANUAL`. This string should specify what the next steps are for the manual delivery to be completed.
* `file` Only applicable if `deliverable.types` contains `DOWNLOADABLE`. If wanting to upload a file, make sure to send the request as a Multipart form instead of JSON.
* `webhook` Only applicable if `deliverable.types` contains `DYNAMIC`. This string should be your dynamic webhook endpoint, which we ping following a successful purchase.
* `stock` Specifies how much stock there is for the deliverable. Not required if `deliverable.types` contains `TEXT` as it is calculated automatically. If not present, stock will be set to infinite.
* `types` Array with values of the deliverable type(s) this product variant contains. Supported values:
* `DOWNLOADABLE` Downloadable file of any type.
* `TEXT` Text products delivered one-by-one.
* `DYNAMIC` Generate a product via your webhook URL.
* `MANUAL` A product that is manually carried out and/or delivered.
The product variant pricing array, contains the following values:
* `humble` Whether the product is of a "Pay what you want" type. If set to `true`, the customer can add an extra amount of their choosing on top of the price.
* `frequency` array that specifies how often a product should be charged. Consists of two values:
* `value` that specifies the period duration
* `interval` that specifies the interval between values. Can be days, weeks, months. Up to 1 year.
* `type` that contains a string of the charge frequency. One of two values:
* `SINGLE_PAYMENT` for one-off charges
* `SUBSCRIPTION` for recurring charges
* At the moment, only Stripe is supported for subscriptions
* `price` which contains the product price array. Consists of two values:
* `price` product price, in cents
* `currency` Country ISO code of the currency the product is priced in
The minimum amount of stock a customer is required to purchase.
The maximum amount of stock a customer is allowed to purchase. If set to null, the customer can purchase an unlimited amount of quantity.
The bulk discount values of the product. Array consists of:
* `minimum_purchase_amount` The quantity at which the bulk discount gets triggered.
* `discount_percentage` The discount value (in percentage) that gets applied to the product price.
This specifies which payment methods are available for the customer to check out with. Your store has to have a payment method activated in order for these to be set.
* Consists of at least one of the below values:
* `PAYPAL` PayPal
* `STRIPE` Stripe
* `CASHAPP` Cash App
* `PADDLE` Paddle
* `AUTHNET` Authorize.net
* `SQUARE` Square
* Cryptocurrency payment methods:
* `BTC` Bitcoin
* `LTC` Litecoin
* `ETH` Ethereum
* `XMR` Monero
* `BNB` Binance BNB
* `TRX` Tron
* `MATIC` Polygon
* `ETH_USDT` USDT (ETH network)
* `ETH_USDC` USDC (ETH network)
* `ETH_UNI` UNI (ETH network)
* `ETH_SHIB` Shiba (ETH network)
* `ETH_DAI` DAI (ETH network)
* `BNB_USDT` USDT (BSC network)
* `BNB_USDC` USDC (BSC network)
* `TRX_USDT` USDT (TRX network)
* `TRX_USDC` USDC (TRX network)
Array of additional settings pertaining to the product variant. Consists of:
* `quantity_increments` that specifies by how much a product can be incremented.
* The default is 1, which lets a customer purchase a quantity of 1,2,3 and so on
* When set to e.g. 2, the customer can only purchase a quantity of 1,3,5 and so on. A quantity of 2 would end up not being allowed.
* `discord_data_required` which specifies whether a customer is required to authorize their Discord account before proceeding with the purchase. If enabled, a customer can not check out before linking their Discord account.
The order of this variant relative to all other variants within the product
The time at which this product variant was first created.
The time at which this product variant was last updated.
The time at which this product variant was deleted.
The relevant product details attached to this variant (readonly). Consists of additional information input(s) of the product. Additional information input array consists of:
* `required` specifying whether the additional information is required
* `key` unique key of the additional information input
* `type` One of the following
* `TEXT`
* `NUMBER`
* `HIDDEN`
* `TEXTAREA`
* `CHECKBOX`
* `label` specifying what the customer needs to enter. Examples below
* `TEXT` What is your in-game username?
* `NUMBER` To what mobile number do you want this delivered?
* `HIDDEN` n.a. *(as this is a hidden input not visible to the end-user)*
* `TEXTAREA` Please specify what your website should look like.
* `CHECKBOX` Would you like a complimentary drink?
***
# List all product variants (/docs/api/product-variants/list-all-product-variants)
This endpoint allows you to retrieve a paginated list of all your product variants. By default, a maximum of fifteen product variants are shown per page.
## Endpoint
- Method: `GET`
- Path: `/v2/products/{product}/variants`
- Full URL: `https://sell.app/api/v2/products/{product}/variants`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `product` (`integer`, required): The product path parameter.
## Query Parameters
- `limit` (`integer`, optional): Limit the number of blacklist rules returned.
- `page` (`integer`, optional): The page number you are attempting to access.
- `with_drafts` (`boolean`, optional): Include draft variants alongside published variants.
- `only_drafts` (`boolean`, optional): Return only draft variants.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"product_id": {
"type": "integer"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"deliverable": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"removeDuplicate": {
"type": "boolean"
},
"parsingMode": {
"type": "string"
},
"stock": {
"type": "integer"
},
"comment": {
"type": "string"
}
},
"required": [
"removeDuplicate",
"parsingMode",
"stock",
"comment"
]
},
"types": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"data",
"types"
]
},
"pricing": {
"type": "object",
"properties": {
"humble": {
"type": "boolean"
},
"frequency": {
"type": "object",
"properties": {
"value": {
"type": "integer"
},
"interval": {
"type": "string"
}
},
"required": [
"value",
"interval"
]
},
"type": {
"type": "string"
},
"price": {
"type": "object",
"properties": {
"price": {
"type": "string"
},
"currency": {
"type": "string"
}
},
"required": [
"price",
"currency"
]
}
},
"required": [
"humble",
"frequency",
"type",
"price"
]
},
"minimum_purchase_quantity": {
"type": "integer"
},
"maximum_purchase_quantity": {
"type": "null"
},
"bulk_discount": {
"type": "array",
"items": {
"type": "object",
"properties": {
"discount_percentage": {
"type": "integer"
},
"minimum_purchase_amount": {
"type": "integer"
}
},
"required": [
"discount_percentage",
"minimum_purchase_amount"
]
}
},
"payment_methods": {
"type": "array",
"items": {
"type": "string"
}
},
"other_settings": {
"type": "object",
"properties": {
"quantity_increments": {
"type": "integer"
},
"discord_data_required": {
"type": "boolean"
}
},
"required": [
"quantity_increments",
"discord_data_required"
]
},
"order": {
"type": "integer"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"deleted_at": {
"type": "null"
},
"product": {
"type": "object",
"properties": {
"additional_information": {
"type": "array",
"items": {
"type": "object",
"properties": {
"required": {
"type": "boolean"
},
"key": {
"type": "string"
},
"type": {
"type": "string"
},
"label": {
"type": "string"
}
},
"required": [
"required",
"key",
"type",
"label"
]
}
}
},
"required": [
"additional_information"
]
}
},
"required": [
"id",
"product_id",
"title",
"description",
"deliverable",
"pricing",
"minimum_purchase_quantity",
"maximum_purchase_quantity",
"bulk_discount",
"payment_methods",
"other_settings",
"order",
"created_at",
"updated_at",
"deleted_at",
"product"
]
}
},
"links": {
"type": "object",
"properties": {}
},
"meta": {
"type": "object",
"properties": {}
}
},
"required": [
"data",
"links",
"meta"
]
}
```
Example:
```json
{
"data": [
{
"id": 1,
"product_id": 1,
"title": "Default",
"description": "default variant",
"deliverable": {
"data": {
"removeDuplicate": false,
"parsingMode": "COMMA",
"stock": 15,
"comment": "Thanks for the purchase! I'll send you a contract by email. Make sure to sign it with your blood."
},
"types": [
"MANUAL"
]
},
"pricing": {
"humble": false,
"frequency": {
"value": 1,
"interval": "MONTH"
},
"type": "SINGLE_PAYMENT",
"price": {
"price": "1999",
"currency": "USD"
}
},
"minimum_purchase_quantity": 1,
"maximum_purchase_quantity": null,
"bulk_discount": [
{
"discount_percentage": 5,
"minimum_purchase_amount": 2
},
{
"discount_percentage": 10,
"minimum_purchase_amount": 5
}
],
"payment_methods": [
"STRIPE"
],
"other_settings": {
"quantity_increments": 1,
"discord_data_required": false
},
"order": 1,
"created_at": "2024-01-09T23:13:16.000000Z",
"updated_at": "2024-01-10T17:27:01.000000Z",
"deleted_at": null,
"product": {
"additional_information": [
{
"required": true,
"key": "3aecffd000e00e2211e94558007ffc37",
"type": "CHECKBOX",
"label": "Do you agree to handing your soul over?"
}
]
}
}
],
"links": {},
"meta": {}
}
```
# Retrieve a product variant (/docs/api/product-variants/retrieve-a-product-variant)
This endpoint allows you to retrieve a specific product variant by providing the unique identifiers of both the product and variant. Refer to [the list](/api/product-variants#the-product-variant-model) to see which properties are included with product variant objects.
## Endpoint
- Method: `GET`
- Path: `/v2/products/{product}/variants/{variant}`
- Full URL: `https://sell.app/api/v2/products/{product}/variants/{variant}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `product` (`integer`, required): The product path parameter.
- `variant` (`integer`, required): The variant path parameter.
## Query Parameters
- `with_drafts` (`boolean`, optional): Include draft variants alongside published variants.
- `only_drafts` (`boolean`, optional): Return only draft variants.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"product_id": {
"type": "integer"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"deliverable": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"removeDuplicate": {
"type": "boolean"
},
"parsingMode": {
"type": "string"
},
"stock": {
"type": "integer"
},
"comment": {
"type": "string"
},
"serials": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"removeDuplicate",
"parsingMode",
"stock",
"comment",
"serials"
]
},
"types": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"data",
"types"
]
},
"pricing": {
"type": "object",
"properties": {
"humble": {
"type": "boolean"
},
"frequency": {
"type": "object",
"properties": {
"value": {
"type": "integer"
},
"interval": {
"type": "string"
}
},
"required": [
"value",
"interval"
]
},
"type": {
"type": "string"
},
"price": {
"type": "object",
"properties": {
"price": {
"type": "string"
},
"currency": {
"type": "string"
}
},
"required": [
"price",
"currency"
]
}
},
"required": [
"humble",
"frequency",
"type",
"price"
]
},
"minimum_purchase_quantity": {
"type": "integer"
},
"maximum_purchase_quantity": {
"type": "integer"
},
"bulk_discount": {
"type": "array",
"items": {
"type": "object",
"properties": {
"discount_percentage": {
"type": "integer"
},
"minimum_purchase_amount": {
"type": "integer"
}
},
"required": [
"discount_percentage",
"minimum_purchase_amount"
]
}
},
"payment_methods": {
"type": "array",
"items": {
"type": "string"
}
},
"other_settings": {
"type": "object",
"properties": {
"quantity_increments": {
"type": "integer"
},
"discord_data_required": {
"type": "boolean"
}
},
"required": [
"quantity_increments",
"discord_data_required"
]
},
"order": {
"type": "integer"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"deleted_at": {
"type": "null"
},
"product": {
"type": "object",
"properties": {
"additional_information": {
"type": "array",
"items": {
"type": "object",
"properties": {
"required": {
"type": "boolean"
},
"key": {
"type": "string"
},
"type": {
"type": "string"
},
"label": {
"type": "string"
}
},
"required": [
"required",
"key",
"type",
"label"
]
}
}
},
"required": [
"additional_information"
]
}
},
"required": [
"id",
"product_id",
"title",
"description",
"deliverable",
"pricing",
"minimum_purchase_quantity",
"maximum_purchase_quantity",
"bulk_discount",
"payment_methods",
"other_settings",
"order",
"created_at",
"updated_at",
"deleted_at",
"product"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 2,
"product_id": 1,
"title": "Variant Title",
"description": "Variant Description",
"deliverable": {
"data": {
"removeDuplicate": false,
"parsingMode": "COMMA",
"stock": 3,
"comment": "Thanks for the purchase! I'll send you a contract by email. Make sure to sign it with your blood.",
"serials": [
"1",
"2",
"3"
]
},
"types": [
"TEXT",
"MANUAL"
]
},
"pricing": {
"humble": true,
"frequency": {
"value": 1,
"interval": "MONTH"
},
"type": "SINGLE_PAYMENT",
"price": {
"price": "1999",
"currency": "USD"
}
},
"minimum_purchase_quantity": 1,
"maximum_purchase_quantity": 3,
"bulk_discount": [
{
"discount_percentage": 10,
"minimum_purchase_amount": 10
}
],
"payment_methods": [
"BTC",
"STRIPE"
],
"other_settings": {
"quantity_increments": 2,
"discord_data_required": false
},
"order": 1,
"created_at": "2024-01-10T18:47:22.000000Z",
"updated_at": "2024-01-10T18:47:22.000000Z",
"deleted_at": null,
"product": {
"additional_information": [
{
"required": true,
"key": "5ebae238c0afae7f4a4b96b30ff6f34c",
"type": "CHECKBOX",
"label": "I agree to handing over my soul"
}
]
}
}
}
```
# Update a product variant (/docs/api/product-variants/update-a-product-variant)
This endpoint allows you to update a product variant's details.
## Endpoint
- Method: `PATCH`
- Path: `/v2/products/{product}/variants/{variant}`
- Full URL: `https://sell.app/api/v2/products/{product}/variants/{variant}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `product` (`integer`, required): The product path parameter.
- `variant` (`integer`, required): The variant path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"deliverable": {
"type": "object",
"properties": {
"types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"DOWNLOADABLE",
"TEXT",
"DYNAMIC",
"MANUAL",
"LICENSE_KEY",
"BUNDLE"
]
}
},
"data": {
"type": "object",
"properties": {
"stock": {
"type": [
"integer",
"null"
]
},
"serials": {
"type": "array",
"items": {
"type": "string"
}
},
"removeDuplicate": {
"type": "boolean"
},
"parsingMode": {
"type": "string",
"enum": [
"COMMA",
"NEW_LINE",
"SPACE",
"CUSTOM"
]
},
"comment": {
"type": "string"
},
"webhook": {
"type": "string",
"format": "uri"
}
}
}
},
"required": [
"types",
"data"
]
},
"pricing": {
"type": "object",
"properties": {
"humble": {
"type": "boolean"
},
"price": {
"type": "object",
"properties": {
"price": {
"type": "integer"
},
"currency": {
"type": "string"
}
},
"required": [
"price",
"currency"
]
}
},
"required": [
"humble",
"price"
]
},
"minimum_purchase_quantity": {
"type": "integer"
},
"maximum_purchase_quantity": {
"type": [
"integer",
"null"
]
},
"bulk_discount": {
"type": "array",
"items": {
"type": "object",
"properties": {
"minimum_purchase_amount": {
"type": "integer"
},
"discount_percentage": {
"type": "integer"
}
},
"required": [
"minimum_purchase_amount",
"discount_percentage"
]
}
},
"payment_methods": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"enum": [
"AUTHNET",
"BTCPAY",
"CASHAPP",
"COINBASE",
"PADDLE",
"PAYDASH",
"PAYPAL",
"PAYSTACK",
"SQUARE",
"STRIPE",
"VENMO",
"NMI",
"LIFI",
"BTC",
"LTC",
"ETH",
"XMR",
"SOL",
"ADA",
"BNB",
"TRX",
"MATIC",
"ETH_USDT",
"ETH_USDC",
"ETH_UNI",
"ETH_SHIB",
"ETH_DAI",
"BNB_USDT",
"BNB_USDC",
"TRX_USDT",
"TRX_USDC",
"SOL_USDT",
"SOL_USDC"
]
}
},
"other_settings": {
"type": "object",
"properties": {
"quantity_increments": {
"type": "integer"
}
}
}
}
}
```
### Content Type: `multipart/form-data`
Schema:
```json
{
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"deliverable": {
"type": "object",
"properties": {
"types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"DOWNLOADABLE",
"TEXT",
"DYNAMIC",
"MANUAL",
"LICENSE_KEY",
"BUNDLE"
]
}
},
"data": {
"type": "object",
"properties": {
"stock": {
"type": [
"integer",
"null"
]
},
"serials": {
"type": "array",
"items": {
"type": "string"
}
},
"removeDuplicate": {
"type": "boolean"
},
"parsingMode": {
"type": "string",
"enum": [
"COMMA",
"NEW_LINE",
"SPACE",
"CUSTOM"
]
},
"comment": {
"type": "string"
},
"webhook": {
"type": "string",
"format": "uri"
},
"file": {
"type": "string",
"format": "binary"
},
"files": {
"type": "array",
"items": {
"type": "string",
"format": "binary"
}
}
}
}
},
"required": [
"types",
"data"
]
},
"pricing": {
"type": "object",
"properties": {
"humble": {
"type": "boolean"
},
"price": {
"type": "object",
"properties": {
"price": {
"type": "integer"
},
"currency": {
"type": "string"
}
},
"required": [
"price",
"currency"
]
}
},
"required": [
"humble",
"price"
]
},
"minimum_purchase_quantity": {
"type": "integer"
},
"maximum_purchase_quantity": {
"type": [
"integer",
"null"
]
},
"bulk_discount": {
"type": "array",
"items": {
"type": "object",
"properties": {
"minimum_purchase_amount": {
"type": "integer"
},
"discount_percentage": {
"type": "integer"
}
},
"required": [
"minimum_purchase_amount",
"discount_percentage"
]
}
},
"payment_methods": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"enum": [
"AUTHNET",
"BTCPAY",
"CASHAPP",
"COINBASE",
"PADDLE",
"PAYDASH",
"PAYPAL",
"PAYSTACK",
"SQUARE",
"STRIPE",
"VENMO",
"NMI",
"LIFI",
"BTC",
"LTC",
"ETH",
"XMR",
"SOL",
"ADA",
"BNB",
"TRX",
"MATIC",
"ETH_USDT",
"ETH_USDC",
"ETH_UNI",
"ETH_SHIB",
"ETH_DAI",
"BNB_USDT",
"BNB_USDC",
"TRX_USDT",
"TRX_USDC",
"SOL_USDT",
"SOL_USDC"
]
}
},
"other_settings": {
"type": "object",
"properties": {
"quantity_increments": {
"type": "integer"
}
}
}
}
}
```
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"product_id": {
"type": "integer"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"deliverable": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"removeDuplicate": {
"type": "boolean"
},
"parsingMode": {
"type": "string"
},
"stock": {
"type": "integer"
},
"comment": {
"type": "string"
},
"serials": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"removeDuplicate",
"parsingMode",
"stock",
"comment",
"serials"
]
},
"types": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"data",
"types"
]
},
"pricing": {
"type": "object",
"properties": {
"humble": {
"type": "boolean"
},
"frequency": {
"type": "object",
"properties": {
"value": {
"type": "integer"
},
"interval": {
"type": "string"
}
},
"required": [
"value",
"interval"
]
},
"type": {
"type": "string"
},
"price": {
"type": "object",
"properties": {
"price": {
"type": "string"
},
"currency": {
"type": "string"
}
},
"required": [
"price",
"currency"
]
}
},
"required": [
"humble",
"frequency",
"type",
"price"
]
},
"minimum_purchase_quantity": {
"type": "integer"
},
"maximum_purchase_quantity": {
"type": "integer"
},
"bulk_discount": {
"type": "array",
"items": {
"type": "object",
"properties": {
"discount_percentage": {
"type": "integer"
},
"minimum_purchase_amount": {
"type": "integer"
}
},
"required": [
"discount_percentage",
"minimum_purchase_amount"
]
}
},
"payment_methods": {
"type": "array",
"items": {
"type": "string"
}
},
"other_settings": {
"type": "object",
"properties": {
"quantity_increments": {
"type": "integer"
},
"discord_data_required": {
"type": "boolean"
}
},
"required": [
"quantity_increments",
"discord_data_required"
]
},
"order": {
"type": "integer"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"deleted_at": {
"type": "null"
},
"product": {
"type": "object",
"properties": {
"additional_information": {
"type": "array",
"items": {
"type": "object",
"properties": {
"required": {
"type": "boolean"
},
"key": {
"type": "string"
},
"type": {
"type": "string"
},
"label": {
"type": "string"
}
},
"required": [
"required",
"key",
"type",
"label"
]
}
}
},
"required": [
"additional_information"
]
}
},
"required": [
"id",
"product_id",
"title",
"description",
"deliverable",
"pricing",
"minimum_purchase_quantity",
"maximum_purchase_quantity",
"bulk_discount",
"payment_methods",
"other_settings",
"order",
"created_at",
"updated_at",
"deleted_at",
"product"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 2,
"product_id": 1,
"title": "Updated Title",
"description": "Variant Description",
"deliverable": {
"data": {
"removeDuplicate": false,
"parsingMode": "COMMA",
"stock": 3,
"comment": "Thanks for the purchase! I'll send you a contract by email. Make sure to sign it with your blood.",
"serials": [
"1",
"2",
"3"
]
},
"types": [
"TEXT",
"MANUAL"
]
},
"pricing": {
"humble": true,
"frequency": {
"value": 1,
"interval": "MONTH"
},
"type": "SINGLE_PAYMENT",
"price": {
"price": "1999",
"currency": "USD"
}
},
"minimum_purchase_quantity": 1,
"maximum_purchase_quantity": 3,
"bulk_discount": [
{
"discount_percentage": 10,
"minimum_purchase_amount": 10
}
],
"payment_methods": [
"BTC",
"STRIPE"
],
"other_settings": {
"quantity_increments": 2,
"discord_data_required": false
},
"order": 1,
"created_at": "2024-01-10T18:47:22.000000Z",
"updated_at": "2024-01-10T18:47:22.000000Z",
"deleted_at": null,
"product": {
"additional_information": [
{
"required": true,
"key": "5ebae238c0afae7f4a4b96b30ff6f34c",
"type": "CHECKBOX",
"label": "I agree to handing over my soul"
}
]
}
}
}
```
# Create a product (/docs/api/products/create-a-product)
Programmatically create a product using the following endpoint. See the code examples for how to create a new product with the SellApp API.
Unlike other endpoints, we will be using Multipart instead of JSON so we can add a product image.
If you do not wish to add a product image, you may modify the request and use JSON instead.
This will create a **draft** product. To complete the product, create a
variant via [Create a product variant](../product-variants/create-a-product-variant).
## Endpoint
- Method: `POST`
- Path: `/v2/products`
- Full URL: `https://sell.app/api/v2/products`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
None.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"visibility": {
"type": "string",
"enum": [
"PUBLIC",
"ON_HOLD",
"HIDDEN",
"PRIVATE"
]
},
"slug": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"product",
"bundle"
]
},
"section": {
"type": [
"integer",
"null"
]
},
"additional_information": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"text",
"number",
"email",
"phone",
"currency",
"link",
"textarea",
"select",
"radio",
"checkbox-group",
"pillbox",
"checkbox",
"switch",
"date",
"date-range",
"hidden"
]
},
"required": {
"type": "boolean"
},
"label": {
"type": "string"
},
"key": {
"type": "string"
},
"options": {
"type": "array",
"items": {
"type": "string"
}
},
"placeholder": {
"type": "string"
},
"description": {
"type": "string"
},
"variant": {
"type": "string"
},
"date_options": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"type",
"required",
"label"
]
}
},
"other_settings": {
"type": "object",
"properties": {
"redirect_url": {
"type": "string",
"format": "uri"
},
"video_url": {
"type": "string",
"format": "uri"
},
"product_title": {
"type": "string"
},
"product_description": {
"type": "string"
},
"faq": {
"type": "array",
"items": {
"type": "object",
"properties": {
"question": {
"type": "string"
},
"answer": {
"type": "string"
}
},
"required": [
"question",
"answer"
]
}
}
}
}
},
"required": [
"title",
"description",
"visibility"
]
}
```
### Content Type: `multipart/form-data`
Schema:
```json
{
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"visibility": {
"type": "string",
"enum": [
"PUBLIC",
"ON_HOLD",
"HIDDEN",
"PRIVATE"
]
},
"slug": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"product",
"bundle"
]
},
"section": {
"type": [
"integer",
"null"
]
},
"additional_information": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"text",
"number",
"email",
"phone",
"currency",
"link",
"textarea",
"select",
"radio",
"checkbox-group",
"pillbox",
"checkbox",
"switch",
"date",
"date-range",
"hidden"
]
},
"required": {
"type": "boolean"
},
"label": {
"type": "string"
},
"key": {
"type": "string"
},
"options": {
"type": "array",
"items": {
"type": "string"
}
},
"placeholder": {
"type": "string"
},
"description": {
"type": "string"
},
"variant": {
"type": "string"
},
"date_options": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"type",
"required",
"label"
]
}
},
"other_settings": {
"type": "object",
"properties": {
"redirect_url": {
"type": "string",
"format": "uri"
},
"video_url": {
"type": "string",
"format": "uri"
},
"product_title": {
"type": "string"
},
"product_description": {
"type": "string"
},
"faq": {
"type": "array",
"items": {
"type": "object",
"properties": {
"question": {
"type": "string"
},
"answer": {
"type": "string"
}
},
"required": [
"question",
"answer"
]
}
}
}
},
"images": {
"type": "array",
"items": {
"type": "string",
"format": "binary"
},
"maxItems": 4
}
},
"required": [
"title",
"description",
"visibility"
]
}
```
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"slug": {
"type": "string"
},
"description": {
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string"
},
"metadata": {
"type": "object",
"properties": {
"size": {
"type": "integer"
},
"filename": {
"type": "string"
},
"extension": {
"type": "string"
},
"mime_type": {
"type": "string"
}
},
"required": [
"size",
"filename",
"extension",
"mime_type"
]
}
},
"required": [
"path",
"metadata"
]
}
},
"order": {
"type": "integer"
},
"visibility": {
"type": "string"
},
"delivery_text": {
"type": "string"
},
"additional_information": {
"type": "array",
"items": {
"type": "object",
"properties": {
"required": {
"type": "boolean"
},
"key": {
"type": "string"
},
"type": {
"type": "string"
},
"label": {
"type": "string"
}
},
"required": [
"required",
"key",
"type",
"label"
]
}
},
"other_settings": {
"type": "object",
"properties": {
"faq": {
"type": "array",
"items": {
"type": "object",
"properties": {
"answer": {
"type": "string"
},
"question": {
"type": "string"
}
},
"required": [
"answer",
"question"
]
}
},
"video_url": {
"type": "string"
},
"redirect_url": {
"type": "string"
},
"product_title": {
"type": "string"
},
"product_description": {
"type": "string"
}
},
"required": [
"faq",
"video_url",
"redirect_url",
"product_title",
"product_description"
]
},
"deleted_at": {
"type": "null"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"category_id": {
"type": "null"
},
"section_id": {
"type": "null"
},
"section_order": {
"type": "null"
},
"is_discoverable": {
"type": "integer"
},
"variants": {
"type": "array",
"items": {
"type": "string"
}
},
"url": {
"type": "string"
}
},
"required": [
"id",
"title",
"slug",
"description",
"images",
"order",
"visibility",
"delivery_text",
"additional_information",
"other_settings",
"deleted_at",
"created_at",
"updated_at",
"store_id",
"category_id",
"section_id",
"section_order",
"is_discoverable",
"variants",
"url"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 2,
"title": "Immortality Elixir",
"slug": "immortality-elixir",
"description": "Want to live forever? Buy this now and I'll send a digital elixir that converts your soul into an NFT that will roam the internet for eternity!",
"images": [
{
"path": "store/1/listings/qXZHzR15vs09zbfn3yui5jO6QK0IbQP4M6QVydUn.png",
"metadata": {
"size": 39289,
"filename": "qXZHzR15vs09zbfn3yui5jO6QK0IbQP4M6QVydUn",
"extension": "png",
"mime_type": "image/png"
}
}
],
"order": 2,
"visibility": "PUBLIC",
"delivery_text": "Thanks for purchasing! Here is a 20% off coupon for your next purchase: 20FREE24",
"additional_information": [
{
"required": true,
"key": "5ebae238c0afae7f4a4b96b30ff6f34c",
"type": "checkbox",
"label": "I agree to handing over my soul"
},
{
"required": true,
"key": "soul_transfer_email",
"type": "email",
"label": "Soul Transfer Email",
"placeholder": "your.soul@example.com",
"description": "We will send your digital elixir here"
}
],
"other_settings": {
"faq": [
{
"answer": "Yes, trust me!",
"question": "Will I really live forever?"
}
],
"video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"redirect_url": "https://666.com/transfer-soul?customer_email=[customer_email]&order_id=[order_id]",
"product_title": "The real elixir of immortality",
"product_description": "Live forever, online."
},
"deleted_at": null,
"created_at": "2024-01-10T12:16:10.000000Z",
"updated_at": "2024-01-10T12:16:10.000000Z",
"store_id": 1,
"category_id": null,
"section_id": null,
"section_order": null,
"is_discoverable": 1,
"variants": [],
"url": "https://example.sell.app/product/immortality-elixir"
}
}
```
# Delete a product (/docs/api/products/delete-a-product)
This endpoint allows you to delete a product.
This will permanently delete the product and its associated data.
## Endpoint
- Method: `DELETE`
- Path: `/v2/products/{product}`
- Full URL: `https://sell.app/api/v2/products/{product}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `product` (`integer`, required): The product path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"slug": {
"type": "string"
},
"description": {
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string"
},
"metadata": {
"type": "object",
"properties": {
"size": {
"type": "integer"
},
"filename": {
"type": "string"
},
"extension": {
"type": "string"
},
"mime_type": {
"type": "string"
}
},
"required": [
"size",
"filename",
"extension",
"mime_type"
]
}
},
"required": [
"path",
"metadata"
]
}
},
"order": {
"type": "integer"
},
"visibility": {
"type": "string"
},
"delivery_text": {
"type": "string"
},
"additional_information": {
"type": "array",
"items": {
"type": "object",
"properties": {
"required": {
"type": "boolean"
},
"key": {
"type": "string"
},
"type": {
"type": "string"
},
"label": {
"type": "string"
}
},
"required": [
"required",
"key",
"type",
"label"
]
}
},
"other_settings": {
"type": "object",
"properties": {
"faq": {
"type": "array",
"items": {
"type": "object",
"properties": {
"answer": {
"type": "string"
},
"question": {
"type": "string"
}
},
"required": [
"answer",
"question"
]
}
},
"video_url": {
"type": "string"
},
"redirect_url": {
"type": "string"
},
"product_title": {
"type": "string"
},
"product_description": {
"type": "string"
}
},
"required": [
"faq",
"video_url",
"redirect_url",
"product_title",
"product_description"
]
},
"deleted_at": {
"type": "null"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"category_id": {
"type": "null"
},
"section_id": {
"type": "null"
},
"section_order": {
"type": "null"
},
"is_discoverable": {
"type": "integer"
},
"variants": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
}
},
"required": [
"id",
"title"
]
}
},
"url": {
"type": "string"
}
},
"required": [
"id",
"title",
"slug",
"description",
"images",
"order",
"visibility",
"delivery_text",
"additional_information",
"other_settings",
"deleted_at",
"created_at",
"updated_at",
"store_id",
"category_id",
"section_id",
"section_order",
"is_discoverable",
"variants",
"url"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 1,
"title": "Elixir of immortality",
"slug": "elixir-of-immortality",
"description": "Want to live forever? Buy this now and I'll send a digital elixir that converts your soul into an NFT that will roam the internet for eternity!
",
"images": [
{
"path": "store/1/listings/NM6TBKIMzpFJq1MKTV24oMJ1W4UrKCo7NS98nt4K.png",
"metadata": {
"size": 39289,
"filename": "NM6TBKIMzpFJq1MKTV24oMJ1W4UrKCo7NS98nt4K",
"extension": "png",
"mime_type": "image/png"
}
},
{
"path": "store/1/listings/ov6XMb68tRr80zl7sqfN1or7xfqqH5WbZygDEQ8X.png",
"metadata": {
"size": 422373,
"filename": "ov6XMb68tRr80zl7sqfN1or7xfqqH5WbZygDEQ8X",
"extension": "png",
"mime_type": "image/png"
}
}
],
"order": 1,
"visibility": "PUBLIC",
"delivery_text": "Thanks again bud!",
"additional_information": [
{
"required": true,
"key": "3aecffd000e00e2211e94558007ffc37",
"type": "checkbox",
"label": "Do you agree to handing your soul over?"
}
],
"other_settings": {
"faq": [
{
"answer": "Yes, trust me!",
"question": "Will I really live forever?"
}
],
"video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"redirect_url": "https://666.com/transfer-soul?customer_email=[customer_email]&order_id=[order_id]",
"product_title": "The real elixir of immortality",
"product_description": "Live forever, online."
},
"deleted_at": null,
"created_at": "2024-01-09T22:56:49.000000Z",
"updated_at": "2024-01-10T10:00:28.000000Z",
"store_id": 1,
"category_id": null,
"section_id": null,
"section_order": null,
"is_discoverable": 1,
"variants": [
{
"id": 1,
"title": "Default"
}
],
"url": "https://example.sell.app/product/elixir-of-immortality"
}
}
```
# Overview (/docs/api/products)
Products are objects containing variants. When a customer purchases a product, they are sent the respetive deliverable(s) that product's variant contains.
One product can have many variants, each of which have their own price, product deliverable, and pricing.
On this page, we'll dive into the different product endpoints you can use to manage products - and product variants - programmatically. We'll look at how to create, update, and delete products.
## Endpoints [#endpoints]
* [List all products](/api/products/list-all-products)
* [Create a product](/api/products/create-a-product)
* [Retrieve a product](/api/products/retrieve-a-product)
* [Update a product](/api/products/update-a-product)
* [Delete a product](/api/products/delete-a-product)
## The product model [#the-product-model]
The product model contains all the information about the products stores have, including the price, media, and customization options.
### Properties [#properties]
The unique product identifier
The product title.
The unique product slug.
The product description.
The array of product images, displays the following information:
* `path` image path
* `metadata` array of image metadata
* `size` size in bytes
* `filename` file name
* `extension` file extension
* `mime_type` file mime type
The order of the product relative to all other products in your storefront.
The product visibility. One of four values:
* `PUBLIC` Product can be visited and purchased.
* `ON_HOLD` Product can be visited but not be purchased.
* `HIDDEN` Product can be only visited via direct link and purchased.
* `PRIVATE` Product cannot be visited nor purchased.
The product delivery text, shown to customers in addition to the variant deliverables. Useful as a thank you note or offering a discount.
The additional information input(s) of the product. The field supports **16 field types** organized into the following categories:
**Text Input Fields:**
* `text` - Single-line text input
* `number` - Numeric input with validation
* `email` - Email address with RFC 5321 validation
* `phone` - Phone number with country selector and E.164 formatting
* `currency` - Currency amount with currency selector
* `link` - Website URL with validation
* `textarea` - Multi-line text input
**Selection Fields:**
* `select` - Dropdown selection (single or multiple)
* `radio` - Radio button group with visual variants
* `checkbox-group` - Multiple checkbox selection with visual variants
* `pillbox` - Tag-style multi-select with removable pills
**Boolean Fields:**
* `checkbox` - Single yes/no checkbox
* `switch` - Toggle switch (on/off)
**Date Fields:**
* `date` - Single date picker with constraints
* `date-range` - Date range selector with validation
**Special:**
* `hidden` - Hidden field not visible to customer
Each additional\_information field supports the following properties:
**Required Properties (all field types):**
* `type` (string) - Field type from the list above
* `label` (string) - Display label (2-100 characters, must be unique)
* `required` (boolean) - Whether the field is mandatory for checkout
**Optional Properties:**
* `key` (string) - Custom identifier for invoice data (2-100 chars, letters/underscores only). Auto-generated from label if omitted
* `placeholder` (string) - Placeholder text for applicable field types (2-255 characters)
* `description` (string) - Help text displayed below the field (2-255 characters)
* `options` (array) - Available options for selection fields (required for select, radio, checkbox-group, pillbox)
* `variant` (string) - Visual style variant for selection fields and switch
* `date_options` (object) - Date-specific configuration for date and date-range fields
Customization settings of the product, with the following options:
* `faq` Object containing an array of frequently asked questions to be displayed on the product page. Consists of:
* `question` FAQ question.
* `answer` FAQ answer.
* `video_url` URL of a product video, will be displayed on the product page. Supported services: YouTube, Vimeo, Dailymotion, Slideshare, Miro
* `redirect_url` URL you want to redirect your customers to after a successful purchase. The redirect URL can utilize the following dynamic values:
* `[order_id]` ID of the order
* `[customer_email]` email of the customer who placed the order
* `product_title` Meta title tag of the product, will appear in search engines and social media.
* `product_description` Meta description tag of the product, will appear in search engines and social media.
The time at which this product was deleted.
The time at which this product was first created.
The time at which this product was last updated.
The ID of the store this product belongs to.
The ID of the category this product belongs to.
The ID of the section this product belongs to.
The order of the product within the section.
Whether the product can be discovered. One of two values:
* `1` It can be discovered.
* `0` It cannot be discovered.
Variants object containing a number of variant arrays. Variant arrays consist of:
* `id` Variant ID
* `title` Variant title
Displays the full product URL, including storefront domain.
## Field Type Details [#field-type-details]
### Text Input Fields [#text-input-fields]
#### `text` [#text]
Single-line text input with optional placeholder.
**Supported properties:** `placeholder`, `description`
**Max length:** 255 characters
**Example:**
```json
{
"type": "text",
"label": "In-Game Username",
"required": true,
"placeholder": "Enter your username",
"description": "Must match your game account"
}
```
***
#### `number` [#number]
Numeric input with range validation.
**Supported properties:** `placeholder`, `description`
**Range:** -9,007,199,254,740,991 to 9,007,199,254,740,991
**Example:**
```json
{
"type": "number",
"label": "Quantity",
"required": true,
"placeholder": "0"
}
```
***
#### `email` [#email]
Email input.
**Supported properties:** `placeholder`, `description`
**Max length:** 255 characters
**Example:**
```json
{
"type": "email",
"label": "Recovery Email",
"required": false,
"placeholder": "user@example.com",
"description": "For account recovery"
}
```
***
#### `phone` [#phone]
Phone number input with country selector.
**Supported properties:** `description`
**Max length:** 25 characters
**Format:** Automatically normalized to E.164 (+1234567890)
**Example:**
```json
{
"type": "phone",
"label": "Mobile Number",
"required": true,
"description": "For SMS delivery notifications"
}
```
***
#### `currency` [#currency]
Currency amount with currency selector.
**Supported properties:** `description`
**Format:** Stores amount in minor units (cents) with currency code
**Example:**
```json
{
"type": "currency",
"label": "Budget",
"required": true,
"description": "Your maximum budget"
}
```
***
#### `link` [#link]
URL input with validation. Automatically prepends `https://` if missing.
**Supported properties:** `placeholder`, `description`
**Max length:** 2048 characters
**Example:**
```json
{
"type": "link",
"label": "Portfolio Website",
"required": false,
"placeholder": "https://example.com"
}
```
***
#### `textarea` [#textarea]
Multi-line text input.
**Supported properties:** `placeholder`, `description`
**Max length:** 2048 characters
**Example:**
```json
{
"type": "textarea",
"label": "Special Instructions",
"required": false,
"placeholder": "Enter any special requirements...",
"description": "Tell us about customization needs"
}
```
***
### Selection Fields [#selection-fields]
Selection fields require an `options` array and support two formats:
**Simple format (string array):**
```json
"options": ["Option A", "Option B", "Option C"]
```
**Enhanced format (objects with metadata):**
Only supported for `radio`, `checkbox-group`, and `switch` (fieldset variant).
```json
"options": [
{
"label": "Basic Plan",
"value": "basic",
"description": "Perfect for individuals"
},
{
"label": "Pro Plan",
"value": "pro",
"description": "Designed for teams"
}
]
```
**Enhanced option properties:**
* `label` (required) - Display text (1-100 characters)
* `value` (optional) - Stored value (defaults to label if omitted)
* `description` (optional) - Helper text (max 255 characters, only displays in compatible variants)
***
#### `select` [#select]
Dropdown selection field.
**Supported properties:** `placeholder`, `description`, `variant`, `options` (required)
**Options format:** String array only
**Variants:**
* `single` (default) - Single selection
* `multiple` - Multiple selection
**Example:**
```json
{
"type": "select",
"label": "Preferred Region",
"required": true,
"variant": "single",
"options": [
"North America",
"Europe",
"Asia"
],
"placeholder": "Select your region..."
}
```
***
#### `radio` [#radio]
Radio button group for single selection.
**Supported properties:** `description`, `variant` (required), `options` (required)
**Options format:** String array or enhanced objects (for default and cards variants)
**Variants:**
* `default` - Standard radio buttons (supports descriptions)
* `cards` - Card-style options (supports descriptions)
* `row` - Inline horizontal layout
* `pills` - Pill-shaped options
* `buttons` - Button-style options
* `segmented` - Segmented control
**Example with enhanced options:**
```json
{
"type": "radio",
"label": "Subscription Plan",
"required": true,
"variant": "cards",
"options": [
{
"label": "Starter",
"value": "starter",
"description": "$9/month - For individuals"
},
{
"label": "Pro",
"value": "pro",
"description": "$29/month - For teams"
}
]
}
```
***
#### `checkbox-group` [#checkbox-group]
Checkbox group for multiple selections.
**Supported properties:** `description`, `variant` (required), `options` (required)
**Options format:** String array or enhanced objects (for default and cards variants)
**Variants:**
* `default` - Standard checkboxes (supports descriptions)
* `cards` - Card-style checkboxes (supports descriptions)
* `fieldset` - Horizontal inline group
* `pills` - Pill-shaped checkboxes
* `buttons` - Button-style checkboxes
**Example:**
```json
{
"type": "checkbox-group",
"label": "Add-on Services",
"required": false,
"variant": "default",
"options": [
"Gift Wrapping",
"Express Shipping",
"Insurance"
]
}
```
***
#### `pillbox` [#pillbox]
Multi-select with removable pill-shaped tags.
**Supported properties:** `placeholder`, `description`, `options` (required)
**Options format:** String array only
**Example:**
```json
{
"type": "pillbox",
"label": "Programming Languages",
"required": true,
"options": [
"JavaScript",
"Python",
"Java",
"Go"
],
"placeholder": "Choose languages..."
}
```
***
### Boolean Fields [#boolean-fields]
#### `checkbox` [#checkbox]
Single yes/no checkbox.
**Supported properties:** `description`
**Example:**
```json
{
"type": "checkbox",
"label": "I agree to the Terms of Service",
"required": true,
"description": "You must accept to proceed"
}
```
***
#### `switch` [#switch]
Toggle switch (on/off).
**Supported properties:** `description`, `variant` (required)
**Options:** Only required for `fieldset` variant (supports enhanced format)
**Variants:**
* `single` - Single on/off toggle
* `fieldset` - Multiple switches in a group (requires options)
**Important:** Switch fields are typically **not required** because they represent on/off states where "off" (false) is a valid value. While you can technically set `required: true`, it rarely makes semantic sense for a toggle.
**Example - Single:**
```json
{
"type": "switch",
"label": "Enable Notifications",
"required": false,
"variant": "single"
}
```
**Example - Fieldset:**
```json
{
"type": "switch",
"label": "Privacy Settings",
"required": false,
"variant": "fieldset",
"options": [
{
"label": "Profile Visibility",
"value": "profile_public",
"description": "Make profile public"
},
{
"label": "Activity Feed",
"value": "show_activity",
"description": "Display recent activity"
}
]
}
```
***
### Date Fields [#date-fields]
Date fields support advanced configuration via the `date_options` object:
**Common date\_options properties:**
* `min_date` (string) - Minimum date: "today" or "YYYY-MM-DD"
* `max_date` (string) - Maximum date: "today" or "YYYY-MM-DD"
* `start_day` (integer) - First day of week (0=Sunday, 1=Monday, ..., 6=Saturday, default: 1)
* `clearable` (boolean) - Show clear button (default: false)
* `week_numbers` (boolean) - Display week numbers (default: false)
* `selectable_header` (boolean) - Clickable month/year header (default: false)
**Additional properties for date-range:**
* `min_range` (integer) - Minimum range in days (≥1)
* `max_range` (integer) - Maximum range in days (≥1)
* `with_presets` (boolean) - Show preset buttons (default: false)
* `with_inputs` (boolean) - Show date inputs (default: false)
* `presets` (string) - Space-separated preset list
**Available presets:** `today`, `yesterday`, `thisWeek`, `lastWeek`, `last7Days`, `last14Days`, `last30Days`, `thisMonth`, `lastMonth`, `last3Months`, `last6Months`, `thisQuarter`, `lastQuarter`, `thisYear`, `lastYear`, `yearToDate`
***
#### `date` [#date]
Single date picker.
**Supported properties:** `placeholder`, `description`, `date_options`
**Example:**
```json
{
"type": "date",
"label": "Delivery Date",
"required": true,
"placeholder": "Select a date...",
"date_options": {
"min_date": "today",
"max_date": "2025-12-31",
"start_day": 1,
"clearable": true
}
}
```
***
#### `date-range` [#date-range]
Date range picker.
**Supported properties:** `placeholder`, `description`, `date_options`
**Example:**
```json
{
"type": "date-range",
"label": "Rental Period",
"required": true,
"placeholder": "Select rental period...",
"description": "Minimum 3 days, maximum 30 days",
"date_options": {
"min_date": "today",
"max_date": "2026-06-30",
"min_range": 3,
"max_range": 30,
"start_day": 1,
"clearable": true,
"with_presets": true,
"presets": "last7Days last14Days last30Days thisMonth"
}
}
```
***
### Special Fields [#special-fields]
#### `hidden` [#hidden]
Hidden field not visible to customers.
**Supported properties:** None
**Note:** Still requires a `label` for internal identification.
**Example:**
```json
{
"type": "hidden",
"label": "Campaign Source",
"required": false,
"key": "utm_source"
}
```
***
## Validation Rules [#validation-rules]
### Field-Level Validation [#field-level-validation]
* `type` - Must be a valid field type from the supported list
* `label` - Required, 2-100 characters, must be unique, cannot use reserved names
* `required` - Required, must be boolean
* `key` - Optional, 2-100 characters, letters and underscores only, must be unique
* `placeholder` - Optional, 2-255 characters (only for supported field types)
* `description` - Optional, 2-255 characters (only for supported field types)
* `options` - Required for select, radio, checkbox-group, pillbox. Required for switch with fieldset variant
* `variant` - Required for select, radio, checkbox-group, switch. Must be valid variant for the field type
### Reserved Field Labels [#reserved-field-labels]
These labels are reserved and cannot be used:
* `purchase_quantity`
* `customer_email`
* `payment_method`
* `extra`
### Options Validation [#options-validation]
**String options:**
* Each option: 1-100 characters
**Enhanced options (objects):**
* `label` - Required, 1-100 characters
* `value` - Optional, 1-100 characters (defaults to label)
* `description` - Optional, max 255 characters
### Date Options Validation [#date-options-validation]
* `min_date` / `max_date` - Must be "today" or valid `YYYY-MM-DD` format
* `min_date` must be ≤ `max_date` when both are specific dates
* `start_day` - Integer 0-6
* `min_range` / `max_range` - Positive integers ≥1
* `min_range` must be ≤ `max_range`
* Boolean options must be `true` or `false`
* `presets` - Space-separated string of valid preset values
***
# List all products (/docs/api/products/list-all-products)
This endpoint allows you to retrieve a paginated list of all your products. By default, a maximum of fifteen products are shown per page.
## Endpoint
- Method: `GET`
- Path: `/v2/products`
- Full URL: `https://sell.app/api/v2/products`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
None.
## Query Parameters
- `limit` (`integer`, optional): Limit the number of blacklist rules returned.
- `page` (`integer`, optional): The page number you are attempting to access.
- `with_drafts` (`boolean`, optional): Include draft products alongside published products.
- `only_drafts` (`boolean`, optional): Return only draft products.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"slug": {
"type": "string"
},
"description": {
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string"
},
"metadata": {
"type": "object",
"properties": {
"size": {
"type": "integer"
},
"filename": {
"type": "string"
},
"extension": {
"type": "string"
},
"mime_type": {
"type": "string"
}
},
"required": [
"size",
"filename",
"extension",
"mime_type"
]
}
},
"required": [
"path",
"metadata"
]
}
},
"order": {
"type": "integer"
},
"visibility": {
"type": "string"
},
"delivery_text": {
"type": "string"
},
"additional_information": {
"type": "array",
"items": {
"type": "object",
"properties": {
"required": {
"type": "boolean"
},
"key": {
"type": "string"
},
"type": {
"type": "string"
},
"label": {
"type": "string"
}
},
"required": [
"required",
"key",
"type",
"label"
]
}
},
"other_settings": {
"type": "object",
"properties": {
"faq": {
"type": "array",
"items": {
"type": "object",
"properties": {
"answer": {
"type": "string"
},
"question": {
"type": "string"
}
},
"required": [
"answer",
"question"
]
}
},
"video_url": {
"type": "string"
},
"redirect_url": {
"type": "string"
},
"product_title": {
"type": "string"
},
"product_description": {
"type": "string"
}
},
"required": [
"faq",
"video_url",
"redirect_url",
"product_title",
"product_description"
]
},
"deleted_at": {
"type": "null"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"category_id": {
"type": "null"
},
"section_id": {
"type": "null"
},
"section_order": {
"type": "null"
},
"is_discoverable": {
"type": "integer"
},
"variants": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
}
},
"required": [
"id",
"title"
]
}
},
"url": {
"type": "string"
}
},
"required": [
"id",
"title",
"slug",
"description",
"images",
"order",
"visibility",
"delivery_text",
"additional_information",
"other_settings",
"deleted_at",
"created_at",
"updated_at",
"store_id",
"category_id",
"section_id",
"section_order",
"is_discoverable",
"variants",
"url"
]
}
},
"links": {
"type": "object",
"properties": {}
},
"meta": {
"type": "object",
"properties": {}
}
},
"required": [
"data",
"links",
"meta"
]
}
```
Example:
```json
{
"data": [
{
"id": 1,
"title": "Elixir of immortality",
"slug": "elixir-of-immortality",
"description": "Want to live forever? Buy this now and I'll send a digital elixir that converts your soul into an NFT that will roam the internet for eternity!
",
"images": [
{
"path": "store/1/listings/NM6TBKIMzpFJq1MKTV24oMJ1W4UrKCo7NS98nt4K.png",
"metadata": {
"size": 39289,
"filename": "NM6TBKIMzpFJq1MKTV24oMJ1W4UrKCo7NS98nt4K",
"extension": "png",
"mime_type": "image/png"
}
},
{
"path": "store/1/listings/ov6XMb68tRr80zl7sqfN1or7xfqqH5WbZygDEQ8X.png",
"metadata": {
"size": 422373,
"filename": "ov6XMb68tRr80zl7sqfN1or7xfqqH5WbZygDEQ8X",
"extension": "png",
"mime_type": "image/png"
}
}
],
"order": 1,
"visibility": "PUBLIC",
"delivery_text": "Thanks again bud!",
"additional_information": [
{
"required": true,
"key": "3aecffd000e00e2211e94558007ffc37",
"type": "checkbox",
"label": "Do you agree to handing your soul over?"
}
],
"other_settings": {
"faq": [
{
"answer": "Yes, trust me!",
"question": "Will I really live forever?"
}
],
"video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"redirect_url": "https://666.com/transfer-soul?customer_email=[customer_email]&order_id=[order_id]",
"product_title": "The real elixir of immortality",
"product_description": "Live forever, online."
},
"deleted_at": null,
"created_at": "2024-01-09T22:56:49.000000Z",
"updated_at": "2024-01-10T10:00:28.000000Z",
"store_id": 1,
"category_id": null,
"section_id": null,
"section_order": null,
"is_discoverable": 1,
"variants": [
{
"id": 1,
"title": "Default"
}
],
"url": "https://example.sell.app/product/elixir-of-immortality"
}
],
"links": {},
"meta": {}
}
```
# Retrieve a product (/docs/api/products/retrieve-a-product)
This endpoint allows you to retrieve a specific product by providing the unique identifier. Refer to [the list](/api/products#the-product-model) to see which properties are included with product objects.
## Endpoint
- Method: `GET`
- Path: `/v2/products/{product}`
- Full URL: `https://sell.app/api/v2/products/{product}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `product` (`integer`, required): The product path parameter.
## Query Parameters
- `with_drafts` (`boolean`, optional): Include draft products alongside published products.
- `only_drafts` (`boolean`, optional): Return only draft products.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"slug": {
"type": "string"
},
"description": {
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string"
},
"metadata": {
"type": "object",
"properties": {
"size": {
"type": "integer"
},
"filename": {
"type": "string"
},
"extension": {
"type": "string"
},
"mime_type": {
"type": "string"
}
},
"required": [
"size",
"filename",
"extension",
"mime_type"
]
}
},
"required": [
"path",
"metadata"
]
}
},
"order": {
"type": "integer"
},
"visibility": {
"type": "string"
},
"delivery_text": {
"type": "string"
},
"additional_information": {
"type": "array",
"items": {
"type": "object",
"properties": {
"required": {
"type": "boolean"
},
"key": {
"type": "string"
},
"type": {
"type": "string"
},
"label": {
"type": "string"
}
},
"required": [
"required",
"key",
"type",
"label"
]
}
},
"other_settings": {
"type": "object",
"properties": {
"faq": {
"type": "array",
"items": {
"type": "object",
"properties": {
"answer": {
"type": "string"
},
"question": {
"type": "string"
}
},
"required": [
"answer",
"question"
]
}
},
"video_url": {
"type": "string"
},
"redirect_url": {
"type": "string"
},
"product_title": {
"type": "string"
},
"product_description": {
"type": "string"
}
},
"required": [
"faq",
"video_url",
"redirect_url",
"product_title",
"product_description"
]
},
"deleted_at": {
"type": "null"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"category_id": {
"type": "null"
},
"section_id": {
"type": "null"
},
"section_order": {
"type": "null"
},
"is_discoverable": {
"type": "integer"
},
"variants": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
}
},
"required": [
"id",
"title"
]
}
},
"url": {
"type": "string"
}
},
"required": [
"id",
"title",
"slug",
"description",
"images",
"order",
"visibility",
"delivery_text",
"additional_information",
"other_settings",
"deleted_at",
"created_at",
"updated_at",
"store_id",
"category_id",
"section_id",
"section_order",
"is_discoverable",
"variants",
"url"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 1,
"title": "Elixir of immortality",
"slug": "elixir-of-immortality",
"description": "Want to live forever? Buy this now and I'll send a digital elixir that converts your soul into an NFT that will roam the internet for eternity!
",
"images": [
{
"path": "store/1/listings/NM6TBKIMzpFJq1MKTV24oMJ1W4UrKCo7NS98nt4K.png",
"metadata": {
"size": 39289,
"filename": "NM6TBKIMzpFJq1MKTV24oMJ1W4UrKCo7NS98nt4K",
"extension": "png",
"mime_type": "image/png"
}
},
{
"path": "store/1/listings/ov6XMb68tRr80zl7sqfN1or7xfqqH5WbZygDEQ8X.png",
"metadata": {
"size": 422373,
"filename": "ov6XMb68tRr80zl7sqfN1or7xfqqH5WbZygDEQ8X",
"extension": "png",
"mime_type": "image/png"
}
}
],
"order": 1,
"visibility": "PUBLIC",
"delivery_text": "Thanks again bud!",
"additional_information": [
{
"required": true,
"key": "3aecffd000e00e2211e94558007ffc37",
"type": "checkbox",
"label": "Do you agree to handing your soul over?"
}
],
"other_settings": {
"faq": [
{
"answer": "Yes, trust me!",
"question": "Will I really live forever?"
}
],
"video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"redirect_url": "https://666.com/transfer-soul?customer_email=[customer_email]&order_id=[order_id]",
"product_title": "The real elixir of immortality",
"product_description": "Live forever, online."
},
"deleted_at": null,
"created_at": "2024-01-09T22:56:49.000000Z",
"updated_at": "2024-01-10T10:00:28.000000Z",
"store_id": 1,
"category_id": null,
"section_id": null,
"section_order": null,
"is_discoverable": 1,
"variants": [
{
"id": 1,
"title": "Default"
}
],
"url": "https://example.sell.app/product/elixir-of-immortality"
}
}
```
# Update a product (/docs/api/products/update-a-product)
Update a product's details with the following endpoint.
## Endpoint
- Method: `PATCH`
- Path: `/v2/products/{product}`
- Full URL: `https://sell.app/api/v2/products/{product}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `product` (`integer`, required): The product path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"visibility": {
"type": "string",
"enum": [
"PUBLIC",
"ON_HOLD",
"HIDDEN",
"PRIVATE"
]
},
"slug": {
"type": "string"
},
"section": {
"type": [
"integer",
"null"
]
},
"additional_information": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"text",
"number",
"email",
"phone",
"currency",
"link",
"textarea",
"select",
"radio",
"checkbox-group",
"pillbox",
"checkbox",
"switch",
"date",
"date-range",
"hidden"
]
},
"required": {
"type": "boolean"
},
"label": {
"type": "string"
},
"key": {
"type": "string"
},
"options": {
"type": "array",
"items": {
"type": "string"
}
},
"placeholder": {
"type": "string"
},
"description": {
"type": "string"
},
"variant": {
"type": "string"
},
"date_options": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"type",
"required",
"label"
]
}
},
"other_settings": {
"type": "object",
"properties": {
"redirect_url": {
"type": "string",
"format": "uri"
},
"video_url": {
"type": "string",
"format": "uri"
},
"product_title": {
"type": "string"
},
"product_description": {
"type": "string"
},
"faq": {
"type": "array",
"items": {
"type": "object",
"properties": {
"question": {
"type": "string"
},
"answer": {
"type": "string"
}
},
"required": [
"question",
"answer"
]
}
}
}
}
}
}
```
### Content Type: `multipart/form-data`
Schema:
```json
{
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"visibility": {
"type": "string",
"enum": [
"PUBLIC",
"ON_HOLD",
"HIDDEN",
"PRIVATE"
]
},
"slug": {
"type": "string"
},
"section": {
"type": [
"integer",
"null"
]
},
"additional_information": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"text",
"number",
"email",
"phone",
"currency",
"link",
"textarea",
"select",
"radio",
"checkbox-group",
"pillbox",
"checkbox",
"switch",
"date",
"date-range",
"hidden"
]
},
"required": {
"type": "boolean"
},
"label": {
"type": "string"
},
"key": {
"type": "string"
},
"options": {
"type": "array",
"items": {
"type": "string"
}
},
"placeholder": {
"type": "string"
},
"description": {
"type": "string"
},
"variant": {
"type": "string"
},
"date_options": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"type",
"required",
"label"
]
}
},
"other_settings": {
"type": "object",
"properties": {
"redirect_url": {
"type": "string",
"format": "uri"
},
"video_url": {
"type": "string",
"format": "uri"
},
"product_title": {
"type": "string"
},
"product_description": {
"type": "string"
},
"faq": {
"type": "array",
"items": {
"type": "object",
"properties": {
"question": {
"type": "string"
},
"answer": {
"type": "string"
}
},
"required": [
"question",
"answer"
]
}
}
}
},
"images": {
"type": "array",
"items": {
"type": "string",
"format": "binary"
},
"maxItems": 4
}
}
}
```
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"slug": {
"type": "string"
},
"description": {
"type": "string"
},
"images": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string"
},
"metadata": {
"type": "object",
"properties": {
"size": {
"type": "integer"
},
"filename": {
"type": "string"
},
"extension": {
"type": "string"
},
"mime_type": {
"type": "string"
}
},
"required": [
"size",
"filename",
"extension",
"mime_type"
]
}
},
"required": [
"path",
"metadata"
]
}
},
"order": {
"type": "integer"
},
"visibility": {
"type": "string"
},
"delivery_text": {
"type": "string"
},
"additional_information": {
"type": "array",
"items": {
"type": "object",
"properties": {
"required": {
"type": "boolean"
},
"key": {
"type": "string"
},
"type": {
"type": "string"
},
"label": {
"type": "string"
}
},
"required": [
"required",
"key",
"type",
"label"
]
}
},
"other_settings": {
"type": "object",
"properties": {
"faq": {
"type": "array",
"items": {
"type": "object",
"properties": {
"answer": {
"type": "string"
},
"question": {
"type": "string"
}
},
"required": [
"answer",
"question"
]
}
},
"video_url": {
"type": "string"
},
"redirect_url": {
"type": "string"
},
"product_title": {
"type": "string"
},
"product_description": {
"type": "string"
}
},
"required": [
"faq",
"video_url",
"redirect_url",
"product_title",
"product_description"
]
},
"deleted_at": {
"type": "null"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"category_id": {
"type": "null"
},
"section_id": {
"type": "null"
},
"section_order": {
"type": "null"
},
"is_discoverable": {
"type": "integer"
},
"variants": {
"type": "array",
"items": {
"type": "string"
}
},
"url": {
"type": "string"
}
},
"required": [
"id",
"title",
"slug",
"description",
"images",
"order",
"visibility",
"delivery_text",
"additional_information",
"other_settings",
"deleted_at",
"created_at",
"updated_at",
"store_id",
"category_id",
"section_id",
"section_order",
"is_discoverable",
"variants",
"url"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 2,
"title": "Immortality Elixir",
"slug": "immortality-elixir",
"description": "Updated Description",
"images": [
{
"path": "store/1/listings/qXZHzR15vs09zbfn3yui5jO6QK0IbQP4M6QVydUn.png",
"metadata": {
"size": 39289,
"filename": "qXZHzR15vs09zbfn3yui5jO6QK0IbQP4M6QVydUn",
"extension": "png",
"mime_type": "image/png"
}
}
],
"order": 2,
"visibility": "PUBLIC",
"delivery_text": "Thanks for purchasing! Here is a 20% off coupon for your next purchase: 20FREE24",
"additional_information": [
{
"required": true,
"key": "5ebae238c0afae7f4a4b96b30ff6f34c",
"type": "checkbox",
"label": "I agree to handing over my soul"
}
],
"other_settings": {
"faq": [
{
"answer": "Yes, trust me!",
"question": "Will I really live forever?"
}
],
"video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"redirect_url": "https://666.com/transfer-soul?customer_email=[customer_email]&order_id=[order_id]",
"product_title": "The real elixir of immortality",
"product_description": "Live forever, online."
},
"deleted_at": null,
"created_at": "2024-01-10T12:16:10.000000Z",
"updated_at": "2024-01-10T12:16:10.000000Z",
"store_id": 1,
"category_id": null,
"section_id": null,
"section_order": null,
"is_discoverable": 1,
"variants": [],
"url": "https://example.sell.app/product/immortality-elixir"
}
}
```
# Create a section (/docs/api/sections/create-a-section)
This endpoint allows you to create a new section. See the code examples for how to create a new section with the SellApp API.
## Endpoint
- Method: `POST`
- Path: `/v1/sections`
- Full URL: `https://sell.app/api/v1/sections`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
None.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"title": {
"type": "string"
},
"hidden": {
"type": "boolean"
}
},
"required": [
"title",
"hidden"
]
}
```
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"slug": {
"type": "string"
},
"hidden": {
"type": "boolean"
},
"order": {
"type": "integer"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"groups_linked": {
"type": "integer"
},
"products_linked": {
"type": "integer"
},
"groups": {
"type": "array",
"items": {
"type": "string"
}
},
"products": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"title",
"slug",
"hidden",
"order",
"created_at",
"updated_at",
"store_id",
"groups_linked",
"products_linked",
"groups",
"products"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 2,
"title": "Developer Goodies",
"slug": "developer-goodies",
"hidden": false,
"order": 1,
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1,
"groups_linked": 0,
"products_linked": 0,
"groups": [],
"products": []
}
}
```
# Delete a section (/docs/api/sections/delete-a-section)
This endpoint allows you to delete a section.
This will permanently delete the section and its details.
## Endpoint
- Method: `DELETE`
- Path: `/v1/sections/{section}`
- Full URL: `https://sell.app/api/v1/sections/{section}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `section` (`integer`, required): The section path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"slug": {
"type": "string"
},
"hidden": {
"type": "boolean"
},
"order": {
"type": "integer"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"groups_linked": {
"type": "integer"
},
"products_linked": {
"type": "integer"
},
"groups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"group_products": {
"type": "integer"
}
},
"required": [
"id",
"title",
"group_products"
]
}
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"id",
"title",
"description"
]
}
}
},
"required": [
"id",
"title",
"slug",
"hidden",
"order",
"created_at",
"updated_at",
"store_id",
"groups_linked",
"products_linked",
"groups",
"products"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 1,
"title": "Dissection",
"slug": "dissection",
"hidden": false,
"order": 1,
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1,
"groups_linked": 1,
"products_linked": 1,
"groups": [
{
"id": 1,
"title": "Rat race",
"group_products": 1
}
],
"products": [
{
"id": "1",
"title": "This will make me rich!",
"description": "I am sure of it, Pinky."
}
]
}
}
```
# Overview (/docs/api/sections)
Sections are another way to make your SellApp storefront more navigable — they allow you to subdivide your storefront into overviewable parts/sections to streamline the customer browsing experience.
On this page, we'll dive into the different section endpoints you can use to manage sections programmatically. We'll look at how to create, update, and delete sections.
## Endpoints [#endpoints]
* [List all sections](/api/sections/list-all-sections)
* [Create a section](/api/sections/create-a-section)
* [Retrieve a section](/api/sections/retrieve-a-section)
* [Update a section](/api/sections/update-a-section)
* [Delete a section](/api/sections/delete-a-section)
## The section model [#the-section-model]
The section model contains all the information about the sections stores have, including the type, code, and discount amount.
### Properties [#properties]
The unique identifier for the section.
The section title.
The section slug.
The section visibility. One of two values:
* `false`: Section is not hidden and can be seen publicly.
* `true`: Section is hidden and can only be seen via direct link.
The order of the section.
The time at which this section was first created.
The time at which this section was last updated.
The ID of the store this section belongs to.
The amount of groups linked to the section.
The amount of products linked to the section.
An array of groups linked to the section, containing three types of info:
* `id`: The group ID.
* `title`: The group title.
* `group_product`: The amount of products linked to the group.
An array of products linked to the section, containing three types of info:
* `id`: The product ID.
* `title`: The product title.
* `description`: The product description.
***
# List all sections (/docs/api/sections/list-all-sections)
This endpoint allows you to retrieve a paginated list of all your sections. By default, a maximum of fifteen sections are shown per page.
## Endpoint
- Method: `GET`
- Path: `/v1/sections`
- Full URL: `https://sell.app/api/v1/sections`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
None.
## Query Parameters
- `limit` (`integer`, optional): Limit the number of blacklist rules returned.
- `page` (`integer`, optional): The page number you are attempting to access.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"slug": {
"type": "string"
},
"hidden": {
"type": "boolean"
},
"order": {
"type": "integer"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"groups_linked": {
"type": "integer"
},
"products_linked": {
"type": "integer"
},
"groups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"group_products": {
"type": "integer"
}
},
"required": [
"id",
"title",
"group_products"
]
}
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"id",
"title",
"description"
]
}
}
},
"required": [
"id",
"title",
"slug",
"hidden",
"order",
"created_at",
"updated_at",
"store_id",
"groups_linked",
"products_linked",
"groups",
"products"
]
}
},
"links": {
"type": "object",
"properties": {}
},
"meta": {
"type": "object",
"properties": {}
}
},
"required": [
"data",
"links",
"meta"
]
}
```
Example:
```json
{
"data": [
{
"id": 1,
"title": "Dissection",
"slug": "dissection",
"hidden": false,
"order": 1,
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1,
"groups_linked": 1,
"products_linked": 1,
"groups": [
{
"id": 1,
"title": "Rat race",
"group_products": 1
}
],
"products": [
{
"id": "1",
"title": "This will make me rich!",
"description": "I am sure of it, Pinky."
}
]
}
],
"links": {},
"meta": {}
}
```
# Retrieve a section (/docs/api/sections/retrieve-a-section)
This endpoint allows you to retrieve a specific section by providing the unique identifier. Refer to [the list](/api/sections#the-section-model) to see which properties are included with section objects.
## Endpoint
- Method: `GET`
- Path: `/v1/sections/{section}`
- Full URL: `https://sell.app/api/v1/sections/{section}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `section` (`integer`, required): The section path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"slug": {
"type": "string"
},
"hidden": {
"type": "boolean"
},
"order": {
"type": "integer"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"groups_linked": {
"type": "integer"
},
"products_linked": {
"type": "integer"
},
"groups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"group_products": {
"type": "integer"
}
},
"required": [
"id",
"title",
"group_products"
]
}
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"id",
"title",
"description"
]
}
}
},
"required": [
"id",
"title",
"slug",
"hidden",
"order",
"created_at",
"updated_at",
"store_id",
"groups_linked",
"products_linked",
"groups",
"products"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 1,
"title": "Dissection",
"slug": "dissection",
"hidden": false,
"order": 1,
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1,
"groups_linked": 1,
"products_linked": 1,
"groups": [
{
"id": 1,
"title": "Rat race",
"group_products": 1
}
],
"products": [
{
"id": "1",
"title": "This will make me rich!",
"description": "I am sure of it, Pinky."
}
]
}
}
```
# Update a section (/docs/api/sections/update-a-section)
This endpoint allows you to perform an update on a section.
## Endpoint
- Method: `PATCH`
- Path: `/v1/sections/{section}`
- Full URL: `https://sell.app/api/v1/sections/{section}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `section` (`integer`, required): The section path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"title": {
"type": "string"
},
"hidden": {
"type": "boolean"
}
}
}
```
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"slug": {
"type": "string"
},
"hidden": {
"type": "boolean"
},
"order": {
"type": "integer"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"groups_linked": {
"type": "integer"
},
"products_linked": {
"type": "integer"
},
"groups": {
"type": "array",
"items": {
"type": "string"
}
},
"products": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"title",
"slug",
"hidden",
"order",
"created_at",
"updated_at",
"store_id",
"groups_linked",
"products_linked",
"groups",
"products"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 2,
"title": "Developer Goodies V2",
"slug": "developer-goodies-v2",
"hidden": false,
"order": 1,
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1,
"groups_linked": 0,
"products_linked": 0,
"groups": [],
"products": []
}
}
```
# Cancel a subscription immediately with a refund (/docs/api/subscriptions/cancel-a-subscription-immediately-with-a-refund)
To cancel immediately and refund the latest subscription payment, send `cancel_at_period_end: false` with `refund_last_payment: true`.
Set `pro_rated_refund: true` if you want a pro-rated refund instead of a full refund.
## Endpoint
- Method: `PATCH`
- Path: `/v2/subscriptions/{subscription}/cancel`
- Full URL: `https://sell.app/api/v2/subscriptions/{subscription}/cancel`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `subscription` (`integer`, required): The subscription path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"cancel_at_period_end": {
"type": "boolean"
},
"refund_last_payment": {
"type": "boolean"
},
"pro_rated_refund": {
"type": "boolean"
}
},
"required": [
"cancel_at_period_end"
]
}
```
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"invoice_id": {
"type": "integer"
},
"provider": {
"type": "string"
},
"subscription_id": {
"type": "string"
},
"customer_id": {
"type": "string"
},
"customer_email": {
"type": "string"
},
"status": {
"type": "string"
},
"current_period_start": {
"type": "string",
"format": "date-time"
},
"current_period_end": {
"type": "string",
"format": "date-time"
},
"cancel_at_period_end": {
"type": "boolean"
},
"cancellation_in_progress": {
"type": "boolean"
},
"store_id": {
"type": "integer"
},
"product_variant_id": {
"type": "integer"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"invoice_id",
"provider",
"subscription_id",
"customer_id",
"customer_email",
"status",
"current_period_start",
"current_period_end",
"cancel_at_period_end",
"cancellation_in_progress",
"store_id",
"product_variant_id",
"created_at",
"updated_at"
]
},
"message": {
"type": "string"
}
},
"required": [
"data",
"message"
]
}
```
Example:
```json
{
"data": {
"id": 123,
"invoice_id": 456,
"provider": "stripe",
"subscription_id": "sub_1QwertyExample",
"customer_id": "cus_Example123",
"customer_email": "customer@example.com",
"status": "ACTIVE",
"current_period_start": "2026-03-01T00:00:00.000000Z",
"current_period_end": "2026-04-01T00:00:00.000000Z",
"cancel_at_period_end": true,
"cancellation_in_progress": false,
"store_id": 1,
"product_variant_id": 99,
"created_at": "2026-03-01T00:00:00.000000Z",
"updated_at": "2026-03-23T00:00:00.000000Z"
},
"message": "Subscription will be cancelled at the end of the current period."
}
```
# Cancel a subscription (/docs/api/subscriptions/cancel-a-subscription)
This endpoint lets you cancel an active subscription programmatically.
You can either:
1. Schedule the cancellation for the end of the current billing period.
2. Cancel immediately.
3. Optionally refund the most recent payment when canceling immediately.
Refund options are only supported for immediate cancellations. If you send `cancel_at_period_end: true`, you should not include refund flags.
## Endpoint
- Method: `PATCH`
- Path: `/v2/subscriptions/{subscription}/cancel`
- Full URL: `https://sell.app/api/v2/subscriptions/{subscription}/cancel`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `subscription` (`integer`, required): The subscription path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"cancel_at_period_end": {
"type": "boolean"
},
"refund_last_payment": {
"type": "boolean"
},
"pro_rated_refund": {
"type": "boolean"
}
},
"required": [
"cancel_at_period_end"
]
}
```
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"invoice_id": {
"type": "integer"
},
"provider": {
"type": "string"
},
"subscription_id": {
"type": "string"
},
"customer_id": {
"type": "string"
},
"customer_email": {
"type": "string"
},
"status": {
"type": "string"
},
"current_period_start": {
"type": "string",
"format": "date-time"
},
"current_period_end": {
"type": "string",
"format": "date-time"
},
"cancel_at_period_end": {
"type": "boolean"
},
"cancellation_in_progress": {
"type": "boolean"
},
"store_id": {
"type": "integer"
},
"product_variant_id": {
"type": "integer"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"id",
"invoice_id",
"provider",
"subscription_id",
"customer_id",
"customer_email",
"status",
"current_period_start",
"current_period_end",
"cancel_at_period_end",
"cancellation_in_progress",
"store_id",
"product_variant_id",
"created_at",
"updated_at"
]
},
"message": {
"type": "string"
}
},
"required": [
"data",
"message"
]
}
```
Example:
```json
{
"data": {
"id": 123,
"invoice_id": 456,
"provider": "stripe",
"subscription_id": "sub_1QwertyExample",
"customer_id": "cus_Example123",
"customer_email": "customer@example.com",
"status": "ACTIVE",
"current_period_start": "2026-03-01T00:00:00.000000Z",
"current_period_end": "2026-04-01T00:00:00.000000Z",
"cancel_at_period_end": true,
"cancellation_in_progress": false,
"store_id": 1,
"product_variant_id": 99,
"created_at": "2026-03-01T00:00:00.000000Z",
"updated_at": "2026-03-23T00:00:00.000000Z"
},
"message": "Subscription will be cancelled at the end of the current period."
}
```
# Overview (/docs/api/subscriptions)
Subscriptions represent recurring product purchases made through your store. The V2 subscriptions API currently exposes one cancellation route, which can either cancel immediately or schedule cancellation for the end of the current billing period depending on the request body you send.
Both endpoint pages below document the same `PATCH /v2/subscriptions/{subscription}/cancel`
route. They are split out to show the two main request-body patterns.
## Endpoints [#endpoints]
* [Cancel a subscription](/api/subscriptions/cancel-a-subscription)
* [Cancel a subscription immediately with a refund](/api/subscriptions/cancel-a-subscription-immediately-with-a-refund)
## The subscription model [#the-subscription-model]
The subscription model contains the key billing and customer details associated with a recurring subscription.
### Properties [#properties]
*(read-only)* The unique identifier for the subscription record.
*(read-only)* The original invoice ID linked to this subscription, if available.
*(read-only)* The billing provider handling the subscription, such as `stripe` or `paypal`.
*(read-only)* The provider subscription identifier.
*(read-only)* The provider customer identifier.
*(read-only)* The customer email associated with the subscription.
*(read-only)* The current subscription status, such as `ACTIVE` or `CANCELED`.
*(read-only)* When the current billing period started.
*(read-only)* When the current billing period ends or ended.
*(read-only)* Whether the subscription is scheduled to cancel at the end of the current billing period.
*(read-only)* Whether an immediate cancellation request has been accepted and is still waiting on provider webhook sync.
*(read-only)* The ID of the store this subscription belongs to.
*(read-only)* The ID of the subscribed product variant.
*(read-only)* Time at which the subscription record was created.
*(read-only)* Time at which the subscription record was last updated.
***
# Overview (/docs/api/tickets)
Tickets are a way to communicate with visitors and customers alike. They help answer questions from potential customers, and streamline post-purchase conversations with existing customers.
On this page, we'll dive into the different ticket endpoints you can use to manage tickets programmatically. We'll look at how to query and reply to tickets.
## Endpoints [#endpoints]
* [List all tickets](/api/tickets/list-all-tickets)
* [Retrieve specific ticket](/api/tickets/retrieve-specific-ticket)
* [List all ticket messages](/api/tickets/list-all-ticket-messages)
* [Reply to ticket](/api/tickets/reply-to-ticket)
* [Retrieve specific ticket message](/api/tickets/retrieve-specific-ticket-message)
## The ticket model [#the-ticket-model]
The ticket model contains all the information about your store's tickets, including the ticket's title, status, and customer details.
### Properties [#properties]
The unique identifier for the ticket.
The title of the ticket.
The ticket status. One of two statuses:
* `OPEN`
* `CLOSED`
Array of customer details consisting of two types of information:
* `id`: Unique customer identifier
* `email`: Email associated to the customer's ticket.
Array of order details if ticket is associated with an order. Consists of two types of information:
* `id`: Order ID
* `type`: Order model
The time at which this ticket was first created.
The time at which this ticket was last updated.
The ID of the store this ticket belongs to.
The ID of the user who read the ticket last.
Whether the ticket has been archived, one of two:
* `1`: Ticket is archived.
* `0`: Ticket is not archived.
## The ticket message model [#the-ticket-message-model]
A ticket has many messages. Each ticket message model contains all the information about that specific message, including the ticket's author, content, and ticket ID.
### Properties [#properties-1]
The unique identifier for the ticket message.
The author of the ticket message. One of two statuses:
* `STORE`
* `CUSTOMER`
The details of the ticket message sender. One of two possibilities:
* Username: For users logged into SellApp.
* Email: For users not logged into SellApp.
The ticket message content; the actual message that is sent.
The time at which this ticket was first created.
The time at which this ticket was last updated.
The ID of the ticket this ticket message belongs to.
***
# List all ticket messages (/docs/api/tickets/list-all-ticket-messages)
This endpoint allows you to retrieve a paginated list of all your ticket messages within a specific ticket received. By default, a maximum of fifteen ticket messages are shown per page.
## Endpoint
- Method: `GET`
- Path: `/v1/tickets/{ticket}/messages`
- Full URL: `https://sell.app/api/v1/tickets/{ticket}/messages`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `ticket` (`integer`, required): The ticket path parameter.
## Query Parameters
- `limit` (`integer`, optional): Limit the number of blacklist rules returned.
- `page` (`integer`, optional): The page number you are attempting to access.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"author": {
"type": "string"
},
"sender": {
"type": "string"
},
"content": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"ticket_id": {
"type": "integer"
}
},
"required": [
"id",
"author",
"sender",
"content",
"created_at",
"updated_at",
"ticket_id"
]
}
},
"links": {
"type": "object",
"properties": {}
},
"meta": {
"type": "object",
"properties": {}
}
},
"required": [
"data",
"links",
"meta"
]
}
```
Example:
```json
{
"data": [
{
"id": 1,
"author": "CUSTOMER",
"sender": "e@x.com",
"content": "Hi. I want to buy sell app. do you accept doge?",
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"ticket_id": 1
}
],
"links": {},
"meta": {}
}
```
# List all tickets (/docs/api/tickets/list-all-tickets)
This endpoint allows you to retrieve a paginated list of all your tickets received. By default, a maximum of fifteen tickets are shown per page.
## Endpoint
- Method: `GET`
- Path: `/v1/tickets`
- Full URL: `https://sell.app/api/v1/tickets`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
None.
## Query Parameters
- `limit` (`integer`, optional): Limit the number of blacklist rules returned.
- `page` (`integer`, optional): The page number you are attempting to access.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"status": {
"type": "string"
},
"customer": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"email": {
"type": "string"
}
},
"required": [
"id",
"email"
]
},
"reference": {
"type": "array",
"items": {
"type": "string"
}
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"read_by": {
"type": "integer"
},
"archived": {
"type": "integer"
}
},
"required": [
"id",
"title",
"status",
"customer",
"reference",
"created_at",
"updated_at",
"store_id",
"read_by",
"archived"
]
}
},
"links": {
"type": "object",
"properties": {}
},
"meta": {
"type": "object",
"properties": {}
}
},
"required": [
"data",
"links",
"meta"
]
}
```
Example:
```json
{
"data": [
{
"id": 1,
"title": "acquisition.",
"status": "OPEN",
"customer": {
"id": "cfbbf27a-0595-3234-953d-5f6629fccc9d",
"email": "e@x.com"
},
"reference": [],
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1,
"read_by": 1,
"archived": 0
}
],
"links": {},
"meta": {}
}
```
# Reply to ticket (/docs/api/tickets/reply-to-ticket)
This endpoint allows you to add a reply to a given ticket.
## Endpoint
- Method: `POST`
- Path: `/v1/tickets/{ticket}/messages`
- Full URL: `https://sell.app/api/v1/tickets/{ticket}/messages`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `ticket` (`integer`, required): The ticket path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
- Required: Yes
### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"content": {
"type": "string"
}
},
"required": [
"content"
]
}
```
Example:
```json
{
"content": "Hey thanks for reaching out but we do not accept doge."
}
```
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"author": {
"type": "string"
},
"sender": {
"type": "null"
},
"content": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"ticket_id": {
"type": "integer"
}
},
"required": [
"id",
"author",
"sender",
"content",
"created_at",
"updated_at",
"ticket_id"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 2,
"author": "STORE",
"sender": null,
"content": "Hey thanks for reaching out but we do not accept doge.",
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"ticket_id": 1
}
}
```
# Retrieve specific ticket message (/docs/api/tickets/retrieve-specific-ticket-message)
This endpoint allows you to retrieve a specific ticket message by providing the unique identifier. Refer to [the list](/api/tickets#the-ticket-message-model) to see which properties are included with ticket message objects.
## Endpoint
- Method: `GET`
- Path: `/v1/tickets/{ticket}/messages/{message}`
- Full URL: `https://sell.app/api/v1/tickets/{ticket}/messages/{message}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `ticket` (`integer`, required): The ticket path parameter.
- `message` (`integer`, required): The message path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"author": {
"type": "string"
},
"sender": {
"type": "null"
},
"content": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"ticket_id": {
"type": "integer"
}
},
"required": [
"id",
"author",
"sender",
"content",
"created_at",
"updated_at",
"ticket_id"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 2,
"author": "STORE",
"sender": null,
"content": "Hey thanks for reaching out but we do not accept doge.",
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"ticket_id": 1
}
}
```
# Retrieve specific ticket (/docs/api/tickets/retrieve-specific-ticket)
This endpoint allows you to retrieve a specific ticket by providing the unique identifier. Refer to [the list](/api/tickets#the-ticket-model) to see which properties are included with ticket objects.
## Endpoint
- Method: `GET`
- Path: `/v1/tickets/{ticket}`
- Full URL: `https://sell.app/api/v1/tickets/{ticket}`
- Authentication: `Bearer` token required
## Code Samples
- Available languages: `curl`, `JavaScript`, `Go`, `Python`, `Java`, `C#`.
- PHP code samples are not generated for this API reference.
## Path Parameters
- `ticket` (`integer`, required): The ticket path parameter.
## Query Parameters
None.
## Header Parameters
None.
## Request Body
No request body.
## Responses
### 200
Successful response.
#### Content Type: `application/json`
Schema:
```json
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"status": {
"type": "string"
},
"customer": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"email": {
"type": "string"
}
},
"required": [
"id",
"email"
]
},
"reference": {
"type": "array",
"items": {
"type": "string"
}
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"store_id": {
"type": "integer"
},
"read_by": {
"type": "integer"
},
"archived": {
"type": "integer"
}
},
"required": [
"id",
"title",
"status",
"customer",
"reference",
"created_at",
"updated_at",
"store_id",
"read_by",
"archived"
]
}
},
"required": [
"data"
]
}
```
Example:
```json
{
"data": {
"id": 1,
"title": "acquisition.",
"status": "OPEN",
"customer": {
"id": "cfbbf27a-0595-3234-953d-5f6629fccc9d",
"email": "e@x.com"
},
"reference": [],
"created_at": "2022-12-12T12:12:12.000000Z",
"updated_at": "2022-12-12T12:12:12.000000Z",
"store_id": 1,
"read_by": 1,
"archived": 0
}
}
```
The second step is to fill each of these options in with the values of your choosing, and then saving the changes. Once you've done that, you're good to go!
***
## Affiliate Settings Explained [#affiliate-settings-explained]
The below is an overview of each of the affiliate settings and their respective purpose.
1. **Affiliate Program toggle**: Enable or disable your store's affiliate program
2. **Affiliate Approval toggle**: Automatically or manually approve new affiliate requests
3. **Referral Commission Input**: Specify how much commission an affiliate can earn for each referral.
* You can set either an amount-based value in USD, or a percentage-based value.
4. **Minimum Payout Balance input**: Specify how much an affiliate needs to earn in commissions before being eligible for a payout
5. **Tracking Duration input**: Specify for how long the affiliate can earn a commission on a customer's purchase.
* For example, if this is set to 1 day, the affiliate only has 1 day for the visitor to make a purchase in order for them to be eligible for a commission.
* If they referred a customer 2 days ago, then the affiliate would not be eligible for a commission any longer
* If this is set to 10 days, the affiliate has 10 days for the visitor to make a purchase in order for them to be eligible for a commission
6. **Referrer Order dropdown**: Specify which referrer should be credited with a sale, in the case where a customer clicks on two referral links
* The first referrer option credits is the affiliate who was first in referring the customer to your product
* The last referrer option credits is the affiliate who most recently referred the customer to your product
7. **Payout Methods checkbox**: Select the payment methods you are able to pay affiliates out with
8. **Custom Products toggle**: Override the "Commission Rate Input" from point 6, and instead specify a commission on a product-by-product basis
***
## Frequently Asked Questions [#frequently-asked-questions]
### Can I specify a custom commission rate on an affiliate-by-affiliate basis? [#can-i-specify-a-custom-commission-rate-on-an-affiliate-by-affiliate-basis]
Yes, once you approve an affiliate you can do so in the respective affiliate's slide-over.
### Do I have to configure any code on the storefront? [#do-i-have-to-configure-any-code-on-the-storefront]
No, eveything is configured and ready to go out of the box. No code changes are required, unless you want to hard-code the `data-sell-affiliate` variable in your embed modal.
# Handling Payouts (/docs/handling-payouts)
Payouts can be viewed at any time [in the Payouts dashboard](https://sell.app/dashboard/affiliates/payouts)
***
## Payouts Dashboard [#payouts-dashboard]
[The Payouts dashboard](https://sell.app/dashboard/affiliates/payouts) displays all affiliate payouts. Since all payouts are displayed regardless of their status or payout method, we have added two filters that help narrow things down.
The first filter helps display payouts with a specific status. The status of each payout is either "Due" or "Paid"
The second filter helps display payouts that are to be paid in a specific payment method. This filter can be used in conjunction with the export functionality in order to generate valid CSV exports for bulk payouts.
For example, if you need to filter the payouts table for payouts that are due, and affiliates expecting to receive their payout sent to their PayPal account, you would do the following:
1. Set the **"Status"** dropdown to **"Due"**
2. Set the **"Payout method"** to **"PayPal"**
The resulting table will exclusively display payouts that are due and to be paid out with PayPal. Subsequently, you can export these payouts by clicking the checkbox at the top left -> "Select All" -> "Export"
You will then receive a CSV file that is formatted in such a way that you can import it to your PayPal account and pay all of these affiliates at one time.
Once you have paid the affiliates via the respective payment method, **please make sure to navigate back to the Payouts dashboard and mark the respective payouts as "paid"**
***
## Payout Slide-over [#payout-slide-over]
The payout slide-over provides a breakdown of the payout created. The first section displays a breakdown of how the affiliate's payout is calculated.
The second section displays a table of referrals associated with this payout. Each individual referral can be viewed as well via the respective quick-action button.
The third and final section displays a timeline of the payout, including when it was created, and paid.
The slide-over also displays a number of quick actions: updating a payout's status, and displaying the associated affiliate.
***
## Frequently Asked Questions [#frequently-asked-questions]
### How do I use PayPal Mass Pay? [#how-do-i-use-paypal-mass-pay]
To pay your affiliates with PayPal Mass Pay, you need to own a verified PayPal business account. If this is the case, proceed with applying for PayPal Mass Pay:
1. Sign in to your PayPal account and click the "Pay & Get Paid" button at the top of the page
2. Click ["Payouts"](https://www.paypal.com/payoutsweb/batchFileUpload?entry=nav) that is shown under "Make Payments"
3. Fill in the form by answering the four questions asked
4. Finally, click the "Submit" button
Once done, you will need to wait for up to 3 days for PayPal to review and accept your request
### When are payouts generated? [#when-are-payouts-generated]
Payouts are generated on the first and fifteenth of every month.
### When are referrals eligible for a payout? [#when-are-referrals-eligible-for-a-payout]
Referrals become eligible for a payout once their status is "Accepted" and their eligible for payout date has been met. The eligible for payout date depends on the payment method the customer has paid with:
* **For fiat payment methods**, such as PayPal or Stripe, the eligible for payout date is **30 days** after the purchase has been made.
* This measure is in place to prevent affiliate fraud and factor in potential charge-backs.
* **For crypto payment methods**, such as Bitcoin, the eligible for payout date is **immediately** once the purchase has been made.
* This is because crypto payments are irreversible and are thus not prone to fraud
# Managing Affiliates (/docs/managing-affiliates)
Affiliates can be managed at any time [in the Affiliates dashboard](https://sell.app/dashboard/affiliates)
***
## Affiliates Dashboard [#affiliates-dashboard]
[The Affiliates dashboard](https://sell.app/dashboard/affiliates) provides a general overview of all affiliates present in your store's affiliate program.
The dashboard also helps you perform the following quick actions:
1. Accepting pending affiliate requests
2. Disabling and/or re-enabling affiliates
3. Opening a specific affiliate's slide-over
***
## Affiliate Slide-over [#affiliate-slide-over]
The affiliate slide-over provides a more in-depth overview of an affiliate, which is split up into a number of tabs.
1. The first tab displays an overview of the affiliate's information. Of note is the "Settings" section, which consists of two buttons:
* Affiliate Coupon: Create an affiliate-specific coupon which the affiliate can use for the following
* To further incentivize potential customers to purchase your product(s)
* It's another, privacy-preserving, way of associating an affiliate with a purchase
* Affiliate Rates: Affiliate-specific rates and eligible products which this affiliate can promote
2. The second tab displays a table of recent referrals generated by this affiliate
3. The third tab displays a table of recent payouts associated with this affiliate
4. The fourth and fifth tab display the affiliate's total earnings, and the amount of earnings which have not been paid yet.
***
## Frequently Asked Questions [#frequently-asked-questions]
### Can I disable accepted affiliates at any time? [#can-i-disable-accepted-affiliates-at-any-time]
Yes, you can always disable affiliates with an "accepted" status [in the Affiliates dashboard](https://sell.app/dashboard/affiliates). A disabled affiliate can be re-activated via the dashboard as well.
### Can I modify the "Affiliate Approval" toggle at any time? [#can-i-modify-the-affiliate-approval-toggle-at-any-time]
Yes, all your store's affiliate program settings can be modified at any time.
# Managing Referrals (/docs/managing-referrals)
Referrals can be managed at any time [in the Referrals dashboard](https://sell.app/dashboard/affiliates/referrals)
***
## Referrals Dashboard [#referrals-dashboard]
[The Referrals dashboard](https://sell.app/dashboard/affiliates/referrals) provides a general overview of all referrals generated by affiliates.
The dashboard also helps you perform the following quick actions:
1. Accept, review, or reject a referral
2. Opening a specific referral's slide-over
***
## Referral Slide-over [#referral-slide-over]
The referral slide-over provides a breakdown of the referral created. The first part displays a breakdown of how the affiliate's commission is calculated.
The second part displays a timeline of the referral, including when it was created, reviewed, and accepted.
The slide-over also displays a number of quick actions: updating a referral's status, and displaying the associated invoice or affiliate.
***
## Frequently Asked Questions [#frequently-asked-questions]
### Can I update a previously rejected referral to an accepted status? [#can-i-update-a-previously-rejected-referral-to-an-accepted-status]
No, once you reject a referral, it is no longer possible to update its status to accepted at a later stage. As such, we only advise rejecting a referral if and when you are certain that you don't want to update the status at a later date.
Should you wish to keep the optionality, we advise changing the status to "In Review" instead
# Trustpilot (/docs/trustpilot)
With SellApp, you can automatically invite your customers to leave a review on your Trustpilot page.
***
## Setup Guide [#setup-guide]
To start, you'd want to head over to [your trustpilot invitation settings by clicking here](https://businessapp.b2b.trustpilot.com/invitations/eti-settings).
1. On this page you'll find a unique Trustpilot email address. Click the "Copy email address"
2. With the copied email address, head on over to [your SellApp storefront settings by clicking here](https://sell.app/dashboard/settings?settings=general) and paste the unique email you copied in step 1 into the "Trustpilot Email" input, then click the "Save" button
That's it! Now, whenever a customer makes a purchase, they will automatically receive an email from Trustpilot inviting them to place a review on your Trustpilot page.
### How it works [#how-it-works]
Whenever a sale is made, your Trustpilot email is BCC'ed into the email that is sent to your customer. This BCC'ed Trustpilot email is then utilized by Trustpilot to automatically send out an invitation to the customer's email to leave a review.
The limitation lies in the number of invites you can send out. For non-paying Trustpilot members, you will only be able to send out 100 invitations per month after which the invites stop being sent out. For most stores this is plenty enough, but for others it might make sense to purchase a plan.
For more info, head on over to Trustpilot's [automatic feedback service (AFS) page by clicking here](https://businessapp.b2b.trustpilot.com/invitations/eti-settings).
# Notifications (/docs/creating-notifications)
You may find yourself wanting to receive a notification when some specific event happens on your SellApp store, such as when an order gets completed, a support ticket is created, or another type of event.
* Specify any kind of subscription duration you'd like. Charge customers every X days, weeks, or months. The highest duration supported is currently 1 year, so you cannot set the duration to be more than a year.
* Once saved, customers can purchase this newly created subscription product.
* We'll handle setting up the subscription and notifying the customer if a payment happens to fail.
* You'll be able to see how many subscriptions are active and how many payments have been made in your [SellApp subscription dashboard](https://sell.app/dashboard/subscriptions)
# Discord roling (/docs/discord-roling)
You may find yourself wanting to have your customers join your Discord server and optionally getting a role post-purchase. With SellApp, this is possible by using your own Discord bot.
***
## Video Guide [#video-guide]
We've created a step-by-step video guide that will help you set up and configure your Discord bot correctly. If you prefer a text-based guide, please proceed to scroll down.
***
## Setup and configure bot [#setup-and-configure-bot]
To start setting up the roling functionality, you'll want to create a Discord bot [in the Discord bot dashboard](https://discord.com/developers/applications)
1. Click "New Application" at the top right hand side,
2. Once your bot is created, retrieve your client ID and secret [from here](https://discord.com/developers/applications/\{botidhere}/oauth2/general), then add the following three redirect URL's on the same page:
* [https://sell.app/discord/connect-account](https://sell.app/discord/connect-account)
* [https://sell.app/discord/connect-customer](https://sell.app/discord/connect-customer)
* [https://sell.app/discord/connect-guild](https://sell.app/discord/connect-guild)
3. Finally, retrieve your bot token [from here](https://discord.com/developers/applications/\{botidhere}/bot)
Once done, paste the client ID, client secret, and bot token in [your SellApp settings](https://sell.app/dashboard/settings?settings=other) and save.
***
## Add account and server [#add-account-and-server]
Now that your bot credentials have been set and saved, the next step is to add your account and server.
1. Click "Add Account" in [your SellApp settings](https://sell.app/dashboard/settings?settings=other). You will be redirected to Discord, grant the permissions and you will be redirected back to SellApp.
In that event, we offer a seamless embed modal that can be displayed within your own site, and lets visitors make purchases without leaving your website or be redirected to a SellApp product page.
Let's dive into how you can do so.
***
## Generating embed code [#generating-embed-code]
To start generating embed code, you'll want to navigate [to your products dashboard](https://sell.app/dashboard/listings)
1. For the relevant product(s), toggle them on the left hand side next to the product's title
2. Once you've toggled all of the products you'd like to embed, select the "Generate embed code" option in the navigation bar. Here's how that looks
3. A modal will pop up with a HTML file. Here's what you'll want to do:
1. Copy the `` and place it in your site's `` section
2. Copy the `` and place it right before your site's closing `` section
3. Copy the button(s) and place it in the relevant area where your customer will click
Once done, save your site's code and you'll be good to go. Now, when a visitor clicks on the button that you've pasted, our embed modal will appear and seamlessly guide the visitor through the purchase process.
***
## Embed variables [#embed-variables]
Each embed button can have unique variables set. A list
1. `data-sell-darkmode` Whether the embed is shown in dark mode or light mode. By default, this is set to `false`. Setting the value to `true` will change the embed's design to dark mode.
2. `data-sell-theme` Pass a 6-digit HEX color such as `#FFFFFF` to slightly style the embed.
3. `data-sell-variant` In the event your product has multiple variants and you want to display a specific variant immediately.
4. `data-sell-coupon` Should you wish to automatically apply a coupon code, enter the code here.
5. `data-sell-quantity` To immediately set the purchase quantity, pass a number in this variable.
6. `data-sell-email` Already know the customer's email? Pre-fill it by entering the email here.
7. `data-sell-extra` If the product is priced as "Pay What You Want", you can specify an amount in advance here. Especially useful for wallet top-ups, for example.
8. `data-sell-affiliate` If you want to attribute a sale to an affiliate via the embed, insert the affiliate's identifier in this variable to do so.
9. `data-sell-payment_method` Pre-fill the payment method so the customer doesn't need to select it manually
Looking for a variable that's not in the above list? Send us a message by contacting us via live chat *(found at the bottom right hand corner of this page)*
***
## Checkout example [#checkout-example]
You own a store where customers can purchase credits to use your digital product. You prefer the look of dark mode. Your customers are authenticated, so you are aware of their email address.
One customer, John Doe with email address `johndoe@example.com`, would like to purchase credits for a specific version of your digital product, which happens to be a variant with value `789`.
John intends to top up with 10 credits, so you know the quantity too. Since he is a recurring customer, you would like to give him 10% off with coupon `amazingdiscount`.
With all of the above points in mind, the URL crafted would result in the following: ``
These variables should help streamline your customer's checkout experience and introduce less friction, all in all resulting in a better converting checkout experience.
# Linking a custom domain (/docs/linking-custom-domain)
By default, your SellApp storefront comes with a free subdomain, for example: **admin.sell.app**. However, you can also add a custom domain of your own, for example: **admin.com**
**It's completely free to add a custom domain to your SellApp storefront**
***
## **Video Guide: Root Domain** [#video-guide-root-domain]
In the following video guide we visually show you how to configure a **root** domain such as **example.com**, **bob.com**, or **varrock.osrs**.
For you to follow this guide step-by-step, you will want to change your domain's DNS provider to Cloudflare. It's free and easy to do so.
If you prefer a text-based guide, please proceed to scroll down to "Step 1".
***
## **Video Guide: Subdomain** [#video-guide-subdomain]
In the following video guide we visually show you how to configure a **subdomain** such as **[www.example.com](http://www.example.com)**, **me.bob.com**, or **teleport.varrock.osrs**.
For you to follow this guide step-by-step, you will want to change your domain's DNS provider to Cloudflare. It's free and easy to do so.
If you prefer a text-based guide, please proceed to scroll down to "Step 1".
***
## **Step 1: Buy a custom domain** [#step-1-buy-a-custom-domain]
*If you've already purchased or own a domain name, skip ahead to Step 2.*
If you don't already have a custom domain, you're going to want to buy one. We strongly suggest going with [Cloudflare](https://www.cloudflare.com) as they're easy, affordable, and have a best-in-class DNS system that comes with DDoS protection out of the box.
***
## **Step 2: Add your custom domain to SellApp** [#step-2-add-your-custom-domain-to-sellapp]
To set up your custom domain, **[navigate to your storefront's personalization settings](https://sell.app/dashboard/settings?settings=personalization)** -> **Custom Domain** and enter the custom domain you'd like your SellApp storefront to live on.
You can specify any domain you'd like:
1. A root domain such as **example.com**, **bob.com**, or **varrock.osrs**
2. A subdomain such as **[www.example.com](http://www.example.com)**, **me.bob.com**, or **teleport.varrock.osrs**
***
## **Step 3: Add the CNAME and TXT record to your custom domain's DNS settings** [#step-3-add-the-cname-and-txt-record-to-your-custom-domains-dns-settings]
In your domain's DNS settings, create two **CNAME records** pointing your (sub)domain to **sell-beacon.net** These are the values for the record you should add:
1. **CNAME Record 1**
* **Host/Name:** \*
* **Value**/**Points To:** sell-beacon.net
2. **CNAME Record 2**
* **Host/Name:**
* **@** — If you'd like to link to your root domain *(as mentioned in point 1 above)*.
* **www**, or **me**, or **teleport** — If you'd like to link to your subdomain *(as mentioned in point 2 above)*.
* **Value**/**Points To:** sell-beacon.net
As a result, your store can experience a considerable lift in conversion rate. Now, instead of browsing various pages, customers can:
1. Open a story to view an image/video about a product being used
2. Click on a product link **directly within the story** to immediately navigate to the product page *(or display the product's embed modal)*
3. Do the same as above for various other stories. You can have a story for your products, customer reviews, upcoming product drops, and so on
***
## Creating Stories [#creating-stories]
1. Navigate to [the Stories dashboard by clicking here](https://sell.app/dashboard/stories).
2. Click on the "New Story" button to create your first story
3. Upload up to 30 media files to your story. Each media file:
1. Will be played one after the other
2. Can be linked to a unique product
3. Can have a different "Call to action" text
4. You can sort media files to your liking, the story will play the media in the order you've sorted
5. You can also sort each story to your liking. The order in which you sort a story will be shown when you create the Stories block in the builder.
That's it! You've now created one or multiple Stories. Now, let's head on over to the builder to display your Stories block.
***
## Displaying Stories [#displaying-stories]
1. Navigate to [the storefront builder by clicking here](https://builder.sell.app).
2. Click on the relevant section within which you want to add the "Stories" block
3. Click the "Add block" button in the left sidebar, then select the "Stories" option
4. The "Stories" block will be inserted into the section. Drag and drop it to whichever place you prefer, the whole section is your canvas. *(Don't forget to check the mobile version of your page once done)*
5. If required, you can configure which story/stories to display by clicking on the "Stories" block and doing so in the left sidebar's "Stories Settings"
Once done, click the "Publish" button at the top right to publish your store's changes. You can then visit your site to see the stories block and interact with.
# FAQ (/docs/faq)
This page covers the most common questions that are not answered elsewhere in the documentation.
## General [#general]
### How do I allow customers using a VPN to make purchases? [#how-do-i-allow-customers-using-a-vpn-to-make-purchases]
The VPN check helps protect your store from fraud. If you want to allow VPN-based purchases:
1. Open [your storefront payment settings](https://sell.app/dashboard/settings?settings=payment).
2. Enable **Allow VPN purchases**.
3. Save your changes.
### How do I change my subdomain? [#how-do-i-change-my-subdomain]
Store subdomains cannot currently be changed.
### How do I appeal negative feedback? [#how-do-i-appeal-negative-feedback]
Feedback cannot currently be appealed.
### My store got banned. Can I recover my products or data? [#my-store-got-banned-can-i-recover-my-products-or-data]
Storefronts that violate SellApp rules are reviewed and banned by the internal risk team. Associated products, files, and stock are purged. SellApp does not restore or redistribute that content.
## Products [#products]
### How do I restock my product? [#how-do-i-restock-my-product]
1. Open [the products dashboard](https://sell.app/dashboard/listings).
2. Click the relevant product.
3. Go to the **Content** section and add more stock.
4. Save the product.
### How do I sell serials, codes, keys, or licenses one-by-one? [#how-do-i-sell-serials-codes-keys-or-licenses-one-by-one]
1. Open [the products dashboard](https://sell.app/dashboard/listings).
2. Create a new product or edit an existing one.
3. In the **Content** section, select **Codes & Serials**.
4. Enter your stock in the **Saved Serials** field.
5. Set the correct stock delimiter if needed.
6. Save the product.
### How do I sell a product for under a dollar? [#how-do-i-sell-a-product-for-under-a-dollar]
Payment providers typically require the total order value to be at least one dollar. The usual workaround is to increase the minimum quantity so the total reaches that threshold.
For example, if a product costs `$0.50`, set the minimum quantity to `2`.
## Orders [#orders]
### When should I mark an order as completed, and how do I do so? [#when-should-i-mark-an-order-as-completed-and-how-do-i-do-so]
SellApp automatically detects successful payments and marks orders as completed. In most cases, you should not need to do this manually.
If you still need to mark an order as completed:
1. Open [the orders dashboard](https://sell.app/dashboard/invoices).
2. Click the three-dot menu on the relevant order.
3. Select **Mark as...**.
4. Choose **Mark as completed** and process the change.
### What do pending, voided, and completed mean in my orders dashboard? [#what-do-pending-voided-and-completed-mean-in-my-orders-dashboard]
* **Pending**: The order was started but not yet paid.
* **Voided**: The order was not paid within 24 hours.
* **Completed**: Payment was received and the order was processed successfully.
# Features (/docs/features)
Out of the box, SellApp includes a wide range of features to help you launch, sell, automate delivery, and grow your storefront.
## Core Platform Features [#core-platform-features]
* Digital product delivery with automatic fulfillment
* Built-in storefront hosting and customization
* Multiple payment method integrations
* Fraud protection and risk controls
* Discounting, promotions, and pricing tools
* Affiliate program support
* Subscription and recurring billing support
* Embedded checkout flows
* API access for programmatic integrations
## What You Can Build [#what-you-can-build]
With SellApp, you can sell software, ebooks, memberships, licenses, subscriptions, and other digital products through a single storefront.
## Related Guides [#related-guides]
## Getting Started [#getting-started]
SellApp is built for speed and simplicity. As your business grows, the platform grows with you. These pages cover the core setup flow, feature overview, support options, and common questions.
2. [Go to your account settings](https://cash.app/account/settings)
3. In the "Personal info" section, you should see your email address
4. If it's not there, click the "add" button and follow the steps to enter your personal email address
* *Don't forget to verify your email with the code Cash App sends you*
***
## Step 2: Forward Cash App emails to SellApp [#step-2-forward-cash-app-emails-to-sellapp]
3. Click the "Add a forwarding address" button
4. In the modal that appears, enter `
5. Once you click the "Next" button, Gmail will send our systems an email with a confirmation URL. We automatically forward the URL to your email. Visit this URL and you will be good to go.
6. Once verified, we need to create a filter to only forward emails from Cash App to the email we just linked:
1. In Gmail, [go to the "Forwarding" section by clicking here](https://mail.google.com/mail/u/0/#settings/fwdandpop)
2. Click the blue "creating a filter!" text to open the filter modal
3. In the filter modal that pops up, enter `
4. In the next page, select the "Forward it to" option, and select `