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.
The invoice model
The invoice model contains all the information about the invoices stores have, including the type, code, and discount amount.
Properties
- Name
id
- Type
- integer
- Description
The unique identifier for the invoice.
- Name
payment
- Type
- array
- Description
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, and order total.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).
- Name
status
- Type
- array
- Description
The historical array of the invoice's status. Consists of two parts:
history
Array of historical order statuses.status
Current order status details.
- Name
webhooks
- Type
- array
- Description
The webhook details, if set.
- Name
feedback
- Type
- string
- Description
The customer order feedback, if made.
- Name
created_at
- Type
- timestamp
- Description
The time at which this invoice was first created.
- Name
updated_at
- Type
- timestamp
- Description
The time at which this invoice was last updated.
- Name
store_id
- Type
- integer
- Description
The ID of the store this invoice belongs to.
- Name
coupon_id
- Type
- integer
- Description
The ID of the coupon applied to this order, if set.
- Name
subscription_id
- Type
- integer
- Description
The ID of the subscription belonging to the invoice, if set.
- Name
customer_information
- Type
- array
- Description
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 ofamount
in cents andcountry
as country code.
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.
Optional attributes
- Name
limit
- Type
- integer
- Description
Limit the number of invoices returned
- Name
page
- Type
- integer
- Description
The page number you are attempting to access.
Request
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://sell.app/api/v2/invoices/');
$request->setRequestMethod('GET');
$request->setHeaders([
'accept' => 'application/json',
'Authorization' => 'Bearer {ApiKeyHere}'
]);
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
Response
{
"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": {
// ...
}
}
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.
Required attributes
- Name
customer_email
- Type
- string
- Description
The email where the product will be delivered to once the order is completed.
- Name
payment_method
- Type
- string
- Description
The payment method with which the customer will be paying. One of the following:
PAYPAL
PayPalSTRIPE
StripeCASHAPP
Cash AppCOINBASE
Coinbase CommercePADDLE
PaddlePAYSTACK
PayStackBTCPAY
BitcoinVENMO
VenmoSQUARE
Square
Cryptocurrency payment methods:
BTC
BitcoinLTC
LitecoinETH
EthereumXMR
MoneroSOL
SolanaADA
Cardano
- Name
product_variants
- Type
- array
- Description
The array of product variants the customer is purchasing.
- Required data to be passed:
id
The product variant ID that is being purchased.quantity
Nested within the product variant ID should be the quantity that is being purchased.
- Optional data that can be passed:
additional_information
array of additional information, consists of the unique additional information key and value. Text Example:'897356954c2cd3d41b221e3f24f99bba': 'abcd'
If the additional information is set as required for the associated product variant, then this data is also required to create the invoice.
- Required data to be passed:
Optional attributes
- Name
coupon
- Type
- string
- Description
The coupon ID, if applicable.
- Name
vat_id
- Type
- string
- Description
The VAT ID of the customer, if VAT is enabled.
- Name
country
- Type
- string
- Description
The customer's country code, if applicable/required.
- Name
extra
- Type
- array
- Description
The
Pay What You Want
array, can only be applied if the product has PWYW pricing, containing:amount
in centscurrency
should be the same as the product
Request
$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{
"customer_email": "customer@example.com",
"payment_method": "CASHAPP",
"coupon": "couponCodeHere",
"product_variants": {
"1": {
"quantity": 1,
"additional_information": {
"UniqueAdditionalInfoKeyHere": "textResponseHere"
}
}
}
}');
$request->setRequestUrl('https://sell.app/api/v2/invoices');
$request->setRequestMethod('POST');
$request->setBody($body);
$request->setHeaders([
'Content-Type' => 'application/json',
'accept' => 'application/json',
'Authorization' => 'Bearer {ApiKeyHere}'
]);
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
Response
{
"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"
}
}
}
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 at the top of this page to see which properties are included with invoice objects.
Request
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://sell.app/api/v2/invoices/1');
$request->setRequestMethod('GET');
$request->setHeaders([
'accept' => 'application/json',
'Authorization' => 'Bearer {ApiKeyHere}'
]);
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
Response
{
"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"
}
}
}
Create a checkout session
This endpoint creates a checkout sessions for a pending invoice.
A practical example:
- You first create an invoice via the the create an invoice endpoint
- Then generate a checkout session via this endpoint.
- 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.
Request
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://sell.app/api/v2/invoices/1/checkout');
$request->setRequestMethod('POST');
$request->setHeaders([
'Content-Type' => 'application/json',
'accept' => 'application/json',
'Authorization' => 'Bearer {ApiKeyHere}'
]);
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
Response
{
"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"
},
"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"
}
}
}
}
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.
Request
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://sell.app/api/v2/invoices/1/deliverables');
$request->setRequestMethod('GET');
$request->setHeaders([
'accept' => 'application/json',
'Authorization' => 'Bearer {ApiKeyHere}'
]);
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
Response
{
"invoice_id": 1,
"product_variant_id": 1,
"deliverable": {
"data": {
"serials": [
"YOUR-KEY-HERE-THANKS"
]
},
"types": [
"TEXT"
]
}
}
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.
Request
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://sell.app/api/v2/invoices/1/mark-completed');
$request->setRequestMethod('PATCH');
$request->setHeaders([
'Content-Type' => 'application/json',
'accept' => 'application/json',
'Authorization' => 'Bearer {ApiKeyHere}'
]);
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
Response
{
"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
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.
Request
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://sell.app/api/v2/invoices/1/mark-voided');
$request->setRequestMethod('PATCH');
$request->setHeaders([
'Content-Type' => 'application/json',
'accept' => 'application/json',
'Authorization' => 'Bearer {ApiKeyHere}'
]);
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
Response
{
"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"
}
}
}
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.
Required attributes
- Name
product_variants
- Type
- array
- Description
Array of associated product variant ID('s) to be replaced.
Make sure to pass along the product variant ID(s), not the product ID(s)
Request
$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{
"product_variants": [ 1 ]
}');
$request->setRequestUrl('https://sell.app/api/v2/invoices/1/issue-replacement');
$request->setRequestMethod('PATCH');
$request->setBody($body);
$request->setHeaders([
'Content-Type' => 'application/json',
'accept' => 'application/json',
'Authorization' => 'Bearer {ApiKeyHere}'
]);
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
Response
{
"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"
}
}
}