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 of amount in cents and country as country code.

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

Request

PATCH

/v2/invoices/:id/mark-completed

$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"
    }
  }
}

PATCH/v2/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

/v2/invoices/:id/mark-voided

$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"
    }
  }
}

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

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

PATCH

/v2/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/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"
    }
  }
}

Invoices

The invoice model

Properties

List all invoices

Optional attributes

Request

Response

Create an invoice

Required attributes

Optional attributes

Request

Response

Retrieve an invoice

Request

Response

Create a checkout session

Request

Response

View invoice deliverables

Request

Response

Mark pending invoice completed

Request

Response

Mark pending invoice voided

Request

Response

Issue replacement for completed invoice

Required attributes

Request

Response