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 two parts:
- gateway: Contains payment gateway type, transaction ID, and order total.
- subtotal: Payment subtotal calculation, contains currency, VAT, and total.
Name
customer_information
Type
array
Description
The array of customer information details, consists of:
- id: SellApp user ID (if logged in).
- ip: Customer IP.
- email: Customer email.
- vat_id: Business VAT ID, if applicable and submitted.
- country: Customer country.
- proxied: Boolean; whether the customer is using IP obfuscation software or not.
- location: Customer location (city level).
- browser_agent: Browser agent used to make the purchase.
Name
status
Type
array
Description
The array of order statuses. 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
products
Type
array
Description
Array of products associated with the order, consists of:
- id: Product ID.
- title: Product title.
- url: Product URL.
- variants: Array of product variant details, consisting of ID, title, quantity purchased, and additional information entered.

GET/v1/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.

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

GET

/v1/invoices

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://sell.app/api/v1/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": {
        "gateway": {
          "data": {
            "total": {
              "base": "1000",
              "currency": "USD",
              "units": 1,
              "vat": 100,
              "total": {
                "exclusive": "1000",
                "inclusive": "1100"
              }
            },
            "customer_email": "customer@example.com"
          },
          "type": "PAYPAL"
        },
        "subtotal": {
          "base": "1000",
          "currency": "USD",
          "units": 1,
          "vat": 100,
          "total": {
            "exclusive": "1000",
            "inclusive": "1100"
          }
        },
        "expires_at": "2022-12-12T12:12:12.000000Z"
      },
      "customer_information": {
        "id": 1,
        "ip": "1.3.3.7",
        "email": "customer@example.com",
        "vat_id": "DE123456789",
        "country": "Germany",
        "proxied": false,
        "location": "Munich",
        "browser_agent": "Mozilla\/4.9 (Windows 98; sl-SI; rv:1.9.1.20) Gecko\/20110422 Firefox\/21.0"
      },
      "status": {
        "history": [],
        "status": {
          "setAt": "2022-12-12T12:12:12.000000Z",
          "status": "PENDING",
          "updatedAt": "2022-12-12T12:12:12.000000Z"
        }
      },
      "webhooks": [],
      "feedback": "",
      "created_at": "2022-12-12T12:12:12.000000Z",
      "updated_at": "2022-12-12T12:12:12.000000Z",
      "store_id": 1,
      "coupon_id": null,
      "subscription_id": null,
      "products": [
        {
          "id": 1,
          "title": "This will make me rich!",
          "url": "http:\/\/store.localhost\/product\/thiswillmakemerich",
          "variants": [
            {
              "id": 1,
              "title": "Default",
              "quantity": 1,
              "additional_information": []
            }
          ]
        }
      ]
    }
  ],
  "links": {
    // ...
  },
  "meta": {
    // ...
  }
}

POST/v1/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.

Note that this endpoint is for checking out products which don't have variants. If you'd like to check out a specific product variant, use the invoices V2 endpoint.

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: PayPal
- STRIPE: Stripe
- CASHAPP: Cash App
- COINBASE: Coinbase Commerce
- PADDLE: Paddle
- PAYSTACK: PayStack
- BTCPAY: Bitcoin
- VENMO: Venmo
- SQUARE: Square
Cryptocurrency payment methods:
- BTC: Bitcoin
- LTC: Litecoin
- ETH: Ethereum
- XMR: Monero
- SOL: Solana
- ADA: Cardano
Name
products
Type
array
Description
The array of products the customer is purchasing. Data required to be passed:
- The product ID that is being checked out.
  - Nested within the product ID should be the quantity that is being purchased.

Optional attributes

Name
coupon
Type
string
Description
The coupon ID, if applicable.
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 cents
- currency should be the same as the product

Request

POST

/v1/invoices

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{
  "customer_email": "zuck@fb.com",
  "payment_method": "CASHAPP",
  "products": {
    "1": {
      "quantity": 1
    }
  }
}');

$request->setRequestUrl('https://sell.app/api/v1/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": {
    "gateway": {
      "data": {
        "total": {
          "base": "0",
          "currency": "USD",
          "units": 1,
          "vat": 0,
          "total": {
            "exclusive": "0",
            "inclusive": "0"
          }
        },
        "customer_email": "zuck@fb.com"
      },
      "type": null
    },
    "subtotal": {
      "base": "0",
      "currency": "USD",
      "units": 1,
      "vat": 0,
      "total": {
        "exclusive": "0",
        "inclusive": "0"
      }
    },
    "expires_at": "2022-12-12T12:12:12.000000Z"
  },
  "customer_information": {
    "id": 1,
    "ip": "8.8.8.8",
    "vat": {
      "amount": 0,
      "country": "US"
    },
    "email": "zuck@fb.com",
    "country": "United States",
    "proxied": false,
    "location": "Los Angeles",
    "browser_agent": "Mozilla\/4.9 (Windows 98; sl-SI; rv:1.9.1.20) Gecko\/20110422 Firefox\/21.0"
  },
  "status": {
    "history": [],
    "status": {
      "setAt": "2022-12-12T12:12:12.000000Z",
      "status": "PENDING",
      "updatedAt": "2022-12-12T12:12:12.000000Z"
    }
  },
  "webhooks": [],
  "feedback": "",
  "created_at": "2022-12-12T12:12:12.000000Z",
  "updated_at": "2022-12-12T12:12:12.000000Z",
  "store_id": 1,
  "coupon_id": null,
  "subscription_id": null,
  "products": [
    {
      "id": 1,
      "title": "This will make me rich!",
      "url": "http:\/\/store.localhost\/product\/thiswillmakemerich",
      "variants": [
        {
          "id": 1,
          "title": "Default",
          "quantity": 1,
          "additional_information": []
        }
      ]
    }
  ]
}

POST/v1/invoices/:id/checkout

Create a checkout session

This endpoint allows you to generate a payment URL for the invoice you created above.

You would pass this URL to the customer, so they could make the payment for the generated invoice. If the invoice has a price of 0 (free), it will instead mark the order as complete.

See the code examples for how to create a new invoice payment URL with the SellApp API.

Request

POST

/v1/invoices/:id/checkout

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://sell.app/api/v1/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": {
      "gateway": {
        "data": {
          "total": {
            "base": "100",
            "currency": "USD",
            "units": 1,
            "vat": 0,
            "total": {
              "exclusive": "100",
              "inclusive": "100"
            }
          },
          "customer_email": "zuck@fb.com",
          "transaction_id": "CQEGF35V"
        },
        "type": "COINBASE"
      },
      "subtotal": {
        "base": "0",
        "currency": "USD",
        "units": 1,
        "vat": 0,
        "total": {
          "exclusive": "100",
          "inclusive": "100"
        }
      },
      "expires_at": "2022-12-12T12:12:12.000000Z"
    },
    "customer_information": {
      "id": 1,
      "ip": "8.8.8.8",
      "vat": {
        "amount": 0,
        "country": "US"
      },
      "email": "zuck@fb.com",
      "country": "United States",
      "proxied": false,
      "location": "Los Angeles",
      "browser_agent": "Mozilla\/4.9 (Windows 98; sl-SI; rv:1.9.1.20) Gecko\/20110422 Firefox\/21.0"
    },
    "status": {
      "history": [],
      "status": {
        "setAt": "2022-12-12T12:12:12.000000Z",
        "status": "PENDING",
        "updatedAt": "2022-12-12T12:12:12.000000Z"
      }
    },
    "webhooks": [],
    "feedback": "",
    "created_at": "2022-12-12T12:12:12.000000Z",
    "updated_at": "2022-12-12T12:12:12.000000Z",
    "store_id": 1,
    "coupon_id": null,
    "subscription_id": null,
    "products": [
      {
        "id": 1,
        "title": "This will make me rich!",
        "url": "http:\/\/store.localhost\/product\/thiswillmakemerich",
        "variants": [
          {
            "id": 1,
            "title": "Default",
            "quantity": 1,
            "additional_information": []
          }
        ]
      }
    ]
  } 
}

GET/v1/invoices/:id

Retrieve an invoice

This endpoint allows you to retrieve a specific invoice by providing the unique identifier. Refer to the list at the top of this page to see which properties are included with invoice objects.

Request

GET

/v1/invoices/:id

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://sell.app/api/v1/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": {
    "gateway": {
      "data": {
        "total": {
          "base": "0",
          "currency": "USD",
          "units": 1,
          "vat": 0,
          "total": {
            "exclusive": "0",
            "inclusive": "0"
          }
        },
        "customer_email": "zuck@fb.com"
      },
      "type": null
    },
    "subtotal": {
      "base": "0",
      "currency": "USD",
      "units": 1,
      "vat": 0,
      "total": {
        "exclusive": "0",
        "inclusive": "0"
      }
    },
    "expires_at": "2022-12-12T12:12:12.000000Z"
  },
  "customer_information": {
    "id": 1,
    "ip": "8.8.8.8",
    "vat": {
      "amount": 0,
      "country": "US"
    },
    "email": "zuck@fb.com",
    "country": "United States",
    "proxied": false,
    "location": "Los Angeles",
    "browser_agent": "Mozilla\/4.9 (Windows 98; sl-SI; rv:1.9.1.20) Gecko\/20110422 Firefox\/21.0"
  },
  "status": {
    "history": [],
    "status": {
      "setAt": "2022-12-12T12:12:12.000000Z",
      "status": "PENDING",
      "updatedAt": "2022-12-12T12:12:12.000000Z"
    }
  },
  "webhooks": [],
  "feedback": "",
  "created_at": "2022-12-12T12:12:12.000000Z",
  "updated_at": "2022-12-12T12:12:12.000000Z",
  "store_id": 1,
  "coupon_id": null,
  "subscription_id": null,
  "products": [
    {
      "id": 1,
      "title": "This will make me rich!",
      "url": "http:\/\/store.localhost\/product\/thiswillmakemerich",
      "variants": [
        {
          "id": 1,
          "title": "Default",
          "quantity": 1,
          "additional_information": []
        }
      ]
    }
  ]
}

PATCH/v1/invoices/:id/mark-completed

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.

Request

PATCH

/v1/invoices/:id/mark-completed

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://sell.app/api/v1/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": {
      "gateway": {
        "data": {
          "total": {
            "base": "100",
            "currency": "USD",
            "units": 1,
            "vat": 0,
            "total": {
              "exclusive": "100",
              "inclusive": "100"
            }
          },
          "customer_email": "zuck@fb.com",
          "transaction_id": "CQEGF35V"
        },
        "type": "COINBASE"
      },
      "subtotal": {
        "base": "0",
        "currency": "USD",
        "units": 1,
        "vat": 0,
        "total": {
          "exclusive": "100",
          "inclusive": "100"
        }
      },
      "expires_at": "2022-12-12T12:12:12.000000Z"
    },
    "customer_information": {
      "id": 1,
      "ip": "8.8.8.8",
      "vat": {
        "amount": 0,
        "country": "US"
      },
      "email": "zuck@fb.com",
      "country": "United States",
      "proxied": false,
      "location": "Los Angeles",
      "browser_agent": "Mozilla\/4.9 (Windows 98; sl-SI; rv:1.9.1.20) Gecko\/20110422 Firefox\/21.0"
    },
    "status": {
      "history": [
        {
          "setAt": "2022-12-12T12:12:12.000000Z",
          "status": "PENDING",
          "updatedAt": "2022-12-12T12:12:12.000000Z"
        }
      ],
      "status": {
        "setAt": "2022-12-12T12:12:12.000000Z",
        "status": "COMPLETED",
        "updatedAt": "2022-12-12T12:12:12.000000Z"
      }
    },
    "webhooks": [],
    "feedback": "",
    "created_at": "2022-12-12T12:12:12.000000Z",
    "updated_at": "2022-12-12T12:12:12.000000Z",
    "store_id": 1,
    "coupon_id": null,
    "subscription_id": null
  }
}

PATCH/v1/invoices/:id/mark-voided

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

PATCH

/v1/invoices/:id/mark-voided

$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://sell.app/api/v1/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": {
      "gateway": {
        "data": {
          "total": {
            "base": "100",
            "currency": "USD",
            "units": 1,
            "vat": 0,
            "total": {
              "exclusive": "100",
              "inclusive": "100"
            }
          },
          "customer_email": "zuck@fb.com",
          "transaction_id": "CQEGF35V"
        },
        "type": "COINBASE"
      },
      "subtotal": {
        "base": "0",
        "currency": "USD",
        "units": 1,
        "vat": 0,
        "total": {
          "exclusive": "100",
          "inclusive": "100"
        }
      },
      "expires_at": "2022-12-12T12:12:12.000000Z"
    },
    "customer_information": {
      "id": 1,
      "ip": "8.8.8.8",
      "vat": {
        "amount": 0,
        "country": "US"
      },
      "email": "zuck@fb.com",
      "country": "United States",
      "proxied": false,
      "location": "Los Angeles",
      "browser_agent": "Mozilla\/4.9 (Windows 98; sl-SI; rv:1.9.1.20) Gecko\/20110422 Firefox\/21.0"
    },
    "status": {
      "history": [
        {
          "setAt": "2022-12-12T12:12:12.000000Z",
          "status": "PENDING",
          "updatedAt": "2022-12-12T12:12:12.000000Z"
        }
      ],
      "status": {
        "setAt": "2022-12-12T12:12:12.000000Z",
        "status": "VOIDED",
        "updatedAt": "2022-12-12T12:12:12.000000Z"
      }
    },
    "webhooks": [],
    "feedback": "",
    "created_at": "2022-12-12T12:12:12.000000Z",
    "updated_at": "2022-12-12T12:12:12.000000Z",
    "store_id": 1,
    "coupon_id": null,
    "subscription_id": null
  }
}

PATCH/v1/invoices/:id/issue-replacement

Issue replacement for completed invoice

This endpoint allows you to issue a replacement product for an existing invoice. If a replacement is issued, a new invoice would get created and completed, with the respective product(s) delivered to the customer's email.

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 variants to be replaced. Note: Make sure to enter the product variant ID(s), not the product ID(s).

Request

PATCH

/v1/invoices/:id/issue-replacement

$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/v1/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": {
      "gateway": {
        "data": {
          "total": {
            "base": "100",
            "currency": "USD",
            "units": 1,
            "vat": 0,
            "total": {
              "exclusive": "100",
              "inclusive": "100"
            }
          },
          "customer_email": "zuck@fb.com",
          "transaction_id": "CQEGF35V"
        },
        "type": "COINBASE"
      },
      "subtotal": {
        "base": "0",
        "currency": "USD",
        "units": 1,
        "vat": 0,
        "total": {
          "exclusive": "100",
          "inclusive": "100"
        }
      },
      "expires_at": "2022-12-12T12:12:12.000000Z"
    },
    "customer_information": {
      "id": 1,
      "ip": "8.8.8.8",
      "email": "zuck@fb.com",
      "country": "United States",
      "proxied": false,
      "location": "Los Angeles",
      "browser_agent": "Mozilla\/4.9 (Windows 98; sl-SI; rv:1.9.1.20) Gecko\/20110422 Firefox\/21.0"
    },
    "status": {
      "history": [
        {
          "setAt": "2022-12-12T12:12:12.000000Z",
          "status": "PENDING",
          "updatedAt": "2022-12-12T12:12:12.000000Z"
        }
      ],
      "status": {
        "setAt": "2022-12-12T12:12:12.000000Z",
        "status": "COMPLETED",
        "updatedAt": "2022-12-12T12:12:12.000000Z"
      }
    },
    "webhooks": [],
    "feedback": "",
    "created_at": "2022-12-12T12:12:12.000000Z",
    "updated_at": "2022-12-12T12:12:12.000000Z",
    "store_id": 1,
    "coupon_id": null,
    "subscription_id": null
  }
}