> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shakesco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Invoice

> Create a new invoice and return a payment URL the customer opens to pay

<span style={{display:"none"}}>For the complete documentation index, see [llms.txt](/llms.txt).</span>

Creates an invoice and returns the full invoice object together with a `payment_url` the customer opens to complete payment.

<Warning>
  **Set up private payments before sending private invoices.** To receive a `"private"` invoice you must first register private payments in the Shakesco app for the specific coin you want to receive. If you create an invoice with `type: "private"` without that setup, the invoice is created but payment fails when the customer tries to pay.
</Warning>

<Info>
  **Request at least \$1.** Because of how private transactions settle, every invoice total should be a minimum of \$1. If you need to charge less than \$1, [contact us](https://shakesco.com/contact) first.
</Info>

### Request Body

<ParamField body="type" type="string">
  `"public"` or `"private"`. Private mode uses stealth addresses. Defaults to your account's privacy setting.

  Private invoices require that you have already registered private payments for the coin you want to receive in the Shakesco app. Without that setup, a `"private"` invoice fails at payment time.
</ParamField>

<ParamField body="currency" type="string" required>
  Currency code for the invoice amount (e.g. `"USD"`, `"KES"`). [See all codes](/api-reference/general/codes)
</ParamField>

<ParamField body="items" type="array" required>
  Line items (at least one required)

  <Expandable title="Item fields">
    <ParamField body="description" type="string" required>
      Item name or description
    </ParamField>

    <ParamField body="unit" type="number" required>
      Quantity
    </ParamField>

    <ParamField body="price" type="number" required>
      Unit price in the invoice currency
    </ParamField>

    <ParamField body="image" type="string">
      Optional image URL for the line item
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="payer_email" type="string">
  Customer's email address. Omit or pass `null` for walk-in customers.
</ParamField>

<ParamField body="payer_name" type="string">
  Customer's display name (optional)
</ParamField>

<ParamField body="payer_country" type="string">
  Two-letter country code of the payer (optional)
</ParamField>

<ParamField body="tax_rate" type="number">
  Tax percentage (e.g. `16` for 16%). Defaults to `0`.
</ParamField>

<ParamField body="store_item_ids" type="array">
  Optional array of store item objects to link catalogue items to this invoice.

  <Expandable title="Store item fields">
    <ParamField body="id" type="integer" required>
      The store item's numeric ID
    </ParamField>

    <ParamField body="quantity" type="integer" required>
      Number of units (minimum 1)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="asset" type="string">
  Preferred payment asset: `"BTC"`, `"ETH"`, `"USDT"`, or `"SATS"`. Can be deferred and set by the payer.

  We recommend receiving `"USDT"` or `"SATS"`: both settle fast and cheap. For `"USDT"`, use a private invoice where possible so your financial activity stays confidential.
</ParamField>

<ParamField body="redirect_url" type="string">
  Optional URL the customer is sent to after they finish paying. Must be a valid URL. Use it to return the payer to your own confirmation or order page.
</ParamField>

### Response

Returns the full invoice object with line items.

<ResponseField name="invoice_number" type="string">
  Unique invoice identifier (e.g. `"INV-2026-a1b2c3d4"`)
</ResponseField>

<ResponseField name="payment_url" type="string">
  Encrypted URL the customer opens to complete payment
</ResponseField>

<ResponseField name="status" type="string">
  `"pending"` on creation
</ResponseField>

<ResponseField name="currency" type="string">
  Invoice currency code
</ResponseField>

<ResponseField name="tax_rate" type="number">
  Tax percentage applied
</ResponseField>

<ResponseField name="expires_at" type="string">
  ISO 8601 datetime after which the invoice expires
</ResponseField>

<ResponseField name="amount" type="null">
  Deferred. Set to `null` until the payer initiates payment.
</ResponseField>

<ResponseField name="asset" type="string | null">
  Payment asset, `null` until chosen by the payer
</ResponseField>

<ResponseField name="redirect_url" type="string | null">
  The redirect URL you supplied, or `null` if none was set
</ResponseField>

<ResponseField name="from_store" type="boolean | null">
  Whether the transaction originated from the Shakesco store. `true` for store transactions, `false` for a standard invoice you created through the API, and `null` when it does not apply. Use this to tell store sales apart from your own invoices.
</ResponseField>

<ResponseField name="transaction_items" type="array">
  Line items on the invoice. Each has `description`, `unit`, `price`, and `image`.
</ResponseField>

```javascript theme={null}
const response = await fetch("https://payments.shakesco.com/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "public",
    currency: "USD",
    payer_email: "customer@example.com",
    payer_name: "Jane Doe",
    items: [{ description: "Platform Services", unit: 1, price: 1400 }],
  }),
});
const invoice = await response.json();
```

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": 1,
    "user_id": 42,
    "invoice_number": "INV-2026-a1b2c3d4",
    "status": "pending",
    "type": "public",
    "currency": "USD",
    "tax_rate": "0.00",
    "is_business": true,
    "from_store": false,
    "receiver": "business@example.com",
    "receiver_country": "US",
    "payer_name": "Jane Doe",
    "payer_email": "customer@example.com",
    "payer_country": null,
    "asset": null,
    "amount": null,
    "rate": null,
    "tx_hash_link": null,
    "receipt_number": null,
    "payment_url": "https://pay.shakesco.com/@business/a1b2c3...",
    "redirect_url": "https://yourstore.com/order/complete",
    "expires_at": "2026-05-23T10:00:00.000000Z",
    "scanned_at": null,
    "paid_at": null,
    "store_item_ids": null,
    "created_at": "2026-05-16T10:00:00.000000Z",
    "updated_at": "2026-05-16T10:00:00.000000Z",
    "transaction_items": [
      {
        "id": 1,
        "crypto_transaction_id": 1,
        "description": "Platform Services",
        "unit": "1",
        "price": "1400",
        "image": null,
        "created_at": "2026-05-16T10:00:00.000000Z",
        "updated_at": "2026-05-16T10:00:00.000000Z"
      }
    ]
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": "\"items\" must contain at least 1 items"
  }
  ```
</ResponseExample>