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.

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

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
    product_variants
    Type
    array
    Description

    The array of product variants the customer is purchasing. Data required to be passed:

    • The product variant ID that is being checked out.
      • Nested within the product variant 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
/v2/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",
  "product_variants": {
    "1": {
      "quantity": 1
    }
  }
}');

$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": {
    "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": []
        }
      ]
    }
  ]
}

GET/v2/invoices/:id/deliverables

View deliverables for completed invoice

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

GET
/v2/invoices/:id/deliverables
$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"
      ]
    }
  }
}