Buy extra credits for a partner

Asks Widgetic for an invoice for extra credits, on top of the credits of the contract. Name the dollars; the invoice is for the most whole credits they buy at the list price of a credit (the price a contract may lower belongs to the contract), so it is never for more than you asked: 12.34 buys 123 credits and the invoice says 12.30. The smallest purchase is 10 dollars and one request buys at most 100000 (ask Widgetic for an invoice for more).

Pay the invoice with the link in the answer. When it is paid the credits are added once, for good, to the account of the person who administers the partner, which is the account everything the partner builds is charged to (getPartnerCreditBalance shows it). Extra credits do not expire, unlike the credits of a contract period, which end with it. Nothing is added before the invoice is paid, and an unpaid invoice for extra credits never stops the partner: only an unpaid invoice of the contract does (payment_arrears).

Available only to partners that have an active paid contract in force with Widgetic (NO_PAID_CONTRACT when none is in force) and no overdue contract invoice (CONTRACT_INVOICE_OVERDUE while a contract invoice is past its due day). A partner that has run out of credits during its period can buy more at the list price.

An Idempotency-Key is required, and it is what makes a retry safe: the same key with the same body returns the invoice already issued, the same key with a different body is refused with 422, and a duplicate that arrives while the first is still running is refused with 409. Use one key per purchase you mean to make, and a new key for the next one. At most 10 requests an hour.

Who may ask: the person who administers the partner, or a Widgetic administrator. A key limited to scopes needs billing:write.

POST /partners/{partnerId}/credits/extra-invoice

Buy extra credits for a partner

cURL

curl --request POST \
  --url https://api.widgetic.com/v1/partners/{partnerId}/credits/extra-invoice \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '{
  "usd": 250
}'

200

{
  "success": true,
  "data": {
    "invoiceId": "Example invoiceId",
    "number": "Example number",
    "hostedInvoiceUrl": "Example hostedInvoiceUrl",
    "pdfUrl": "Example pdfUrl",
    "credits": 42,
    "creditPriceUsd": 42,
    "amountUsd": 42,
    "taxUsd": 42,
    "totalUsd": 42,
    "currency": "Example currency",
    "dueDate": "2026-01-15T09:30:00.000Z",
    "dueDays": 42
  },
  "meta": {
    "page": 1,
    "size": 20,
    "total": 135,
    "limit": 20,
    "offset": 0,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "nextCursor": "<string>",
    "warnings": [
      "<string>"
    ]
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key · string · required

A key of your own for this purchase, so that a retry cannot make a second invoice

Required string length: 8 - 50

Pattern: ^[A-Za-z0-9_-]+$

Path Parameters

partnerId · string<uuid> · required

Partner ID

Body

application/json

usd · number · required

The dollars to spend on credits, to the cent: at least 10, at most 100000 in one request. The invoice is for the most whole credits that money buys at the list price of a credit, so it is never for more than this (12.34 buys 123 credits and the invoice says 12.30).

Required range: 10 <= x <= 100000

Example:

250

Response

200

application/json

The invoice was issued

success · boolean · required

Always true on a success.

Example:

true

data · object · required

The invoice for extra credits that was issued, and what paying it adds.

Show child attributes

Example:

{
  "invoiceId": "Example invoiceId",
  "number": "Example number",
  "hostedInvoiceUrl": "Example hostedInvoiceUrl",
  "pdfUrl": "Example pdfUrl",
  "credits": 42,
  "creditPriceUsd": 42,
  "amountUsd": 42,
  "taxUsd": 42,
  "totalUsd": 42,
  "currency": "Example currency",
  "dueDate": "2026-01-15T09:30:00.000Z",
  "dueDays": 42
}

meta · object

Extra information about the answer: where a page sits in a list, the cursor of the next page, or warnings about a call that succeeded with a caveat.

Show child attributes