POST
/
invoices
/
{invoice_id}
/
mark_paid
Mark invoice as paid
curl --request POST \
  --url https://api.withorb.com/v1/invoices/{invoice_id}/mark_paid \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payment_received_date": "2023-09-22",
  "external_id": "external_payment_id_123",
  "notes": "<string>"
}'
{
  "metadata": {},
  "voided_at": "2023-11-07T05:31:56Z",
  "paid_at": "2023-11-07T05:31:56Z",
  "issued_at": "2023-11-07T05:31:56Z",
  "scheduled_issue_at": "2023-11-07T05:31:56Z",
  "auto_collection": {
    "next_attempt_at": "2023-11-07T05:31:56Z",
    "previously_attempted_at": "2023-11-07T05:31:56Z",
    "enabled": true,
    "num_attempts": 123
  },
  "issue_failed_at": "2023-11-07T05:31:56Z",
  "sync_failed_at": "2023-11-07T05:31:56Z",
  "payment_failed_at": "2023-11-07T05:31:56Z",
  "payment_started_at": "2023-11-07T05:31:56Z",
  "amount_due": "8.00",
  "created_at": "2022-05-01T07:01:31+00:00",
  "currency": "USD",
  "customer": {
    "id": "<string>",
    "external_customer_id": "<string>"
  },
  "due_date": "2022-05-30T07:00:00+00:00",
  "id": "<string>",
  "invoice_pdf": "https://assets.withorb.com/invoice/rUHdhmg45vY45DX/qEAeuYePaphGMdFb",
  "invoice_number": "JYEFHK-00001",
  "subscription": {
    "id": "VDGsT23osdLb84KD"
  },
  "total": "8.00",
  "customer_balance_transactions": [
    {
      "id": "cgZa3SXcsPTVyC4Y",
      "created_at": "2022-05-01T07:01:31+00:00",
      "starting_balance": "33.00",
      "ending_balance": "22.00",
      "amount": "11.00",
      "action": "applied_to_invoice",
      "description": "An optional description",
      "invoice": {
        "id": "gXcsPTVyC4YZa3Sc"
      },
      "type": "increment",
      "credit_note": {
        "id": "<string>"
      }
    }
  ],
  "status": "issued",
  "invoice_source": "subscription",
  "shipping_address": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "billing_address": {
    "line1": "<string>",
    "line2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "postal_code": "<string>",
    "country": "<string>"
  },
  "hosted_invoice_url": "<string>",
  "will_auto_issue": true,
  "eligible_to_issue_at": "2023-11-07T05:31:56Z",
  "customer_tax_id": {
    "country": "AD",
    "type": "ad_nrt",
    "value": "<string>"
  },
  "memo": "<string>",
  "credit_notes": [
    {
      "id": "<string>",
      "credit_note_number": "<string>",
      "reason": "<string>",
      "total": "<string>",
      "voided_at": "2022-05-01T07:01:31+00:00",
      "type": "<string>",
      "memo": "<string>"
    }
  ],
  "payment_attempts": [
    {
      "id": "<string>",
      "payment_provider": "stripe",
      "payment_provider_id": "<string>",
      "amount": "<string>",
      "succeeded": true,
      "created_at": "2023-11-07T05:31:56Z",
      "receipt_pdf": "https://assets.withorb.com/receipt/rUHdhmg45vY45DX/qEAeuYePaphGMdFb"
    }
  ],
  "discount": "<any>",
  "discounts": [
    {
      "discount_type": "percentage",
      "applies_to_price_ids": [
        "h74gfhdjvn7ujokd",
        "7hfgtgjnbvc3ujkl"
      ],
      "filters": [
        {
          "field": "price_id",
          "operator": "includes",
          "values": [
            "<any>"
          ]
        }
      ],
      "reason": "<string>",
      "percentage_discount": 0.15
    }
  ],
  "minimum": {
    "minimum_amount": "<string>",
    "filters": [
      {
        "field": "<any>",
        "operator": "<any>",
        "values": "<any>"
      }
    ],
    "applies_to_price_ids": [
      "<string>"
    ]
  },
  "minimum_amount": "<string>",
  "maximum": {
    "maximum_amount": "<string>",
    "filters": [
      {
        "field": "<any>",
        "operator": "<any>",
        "values": "<any>"
      }
    ],
    "applies_to_price_ids": [
      "<string>"
    ]
  },
  "maximum_amount": "<string>",
  "line_items": [
    {
      "amount": "7.00",
      "discount": {
        "discount_type": "percentage",
        "applies_to_price_ids": [
          "h74gfhdjvn7ujokd",
          "7hfgtgjnbvc3ujkl"
        ],
        "filters": [
          {}
        ],
        "reason": "<string>",
        "percentage_discount": 0.15
      },
      "end_date": "2022-02-01T08:00:00+00:00",
      "grouping": "<string>",
      "minimum": {
        "minimum_amount": "<string>",
        "filters": [
          {
            "field": "<any>",
            "operator": "<any>",
            "values": "<any>"
          }
        ],
        "applies_to_price_ids": [
          "<string>"
        ]
      },
      "minimum_amount": "<string>",
      "maximum": {
        "maximum_amount": "<string>",
        "filters": [
          {
            "field": "<any>",
            "operator": "<any>",
            "values": "<any>"
          }
        ],
        "applies_to_price_ids": [
          "<string>"
        ]
      },
      "maximum_amount": "<string>",
      "adjustments": [
        {
          "id": "<string>",
          "is_invoice_level": true,
          "filters": [
            {
              "field": "price_id",
              "operator": "includes",
              "values": [
                "<any>"
              ]
            }
          ],
          "applies_to_price_ids": [
            "<string>"
          ],
          "reason": "<string>",
          "replaces_adjustment_id": "<string>",
          "adjustment_type": "usage_discount",
          "usage_discount": 123,
          "amount": "<string>"
        }
      ],
      "name": "Fixed Fee",
      "quantity": 1,
      "start_date": "2022-02-01T08:00:00+00:00",
      "subtotal": "9.00",
      "adjusted_subtotal": "5.00",
      "credits_applied": "6.00",
      "partially_invoiced_amount": "4.00",
      "sub_line_items": [
        {
          "amount": "9.00",
          "name": "Tier One",
          "quantity": 5,
          "grouping": {
            "key": "region",
            "value": "west"
          },
          "type": "matrix",
          "matrix_config": {
            "dimension_values": [
              "<string>"
            ]
          }
        }
      ],
      "tax_amounts": [
        {
          "tax_rate_description": "<string>",
          "tax_rate_percentage": "<string>",
          "amount": "<string>"
        }
      ],
      "id": "<string>",
      "price": {
        "model_type": "unit",
        "unit_config": {
          "unit_amount": "<string>",
          "scaling_factor": 123
        },
        "metadata": {},
        "id": "<string>",
        "name": "<string>",
        "external_price_id": "<string>",
        "replaces_price_id": "<string>",
        "price_type": "usage_price",
        "created_at": "2023-11-07T05:31:56Z",
        "cadence": "one_time",
        "billing_mode": "in_advance",
        "billing_cycle_configuration": {
          "duration": 123,
          "duration_unit": "day"
        },
        "invoicing_cycle_configuration": {
          "duration": 123,
          "duration_unit": "day"
        },
        "billable_metric": {
          "id": "<string>"
        },
        "dimensional_price_configuration": {
          "dimensional_price_group_id": "<string>",
          "dimension_values": [
            "<string>"
          ]
        },
        "fixed_price_quantity": 123,
        "plan_phase_order": 123,
        "currency": "<string>",
        "conversion_rate": 123,
        "conversion_rate_config": {
          "conversion_rate_type": "unit",
          "unit_config": {
            "unit_amount": "<string>"
          }
        },
        "item": {
          "id": "<string>",
          "name": "<string>"
        },
        "credit_allocation": {
          "currency": "<string>",
          "allows_rollover": true,
          "custom_expiration": {
            "duration": 123,
            "duration_unit": "day"
          }
        },
        "composite_price_filters": [
          {
            "field": "price_id",
            "operator": "includes",
            "values": [
              "<any>"
            ]
          }
        ],
        "discount": {
          "discount_type": "percentage",
          "applies_to_price_ids": [
            "h74gfhdjvn7ujokd",
            "7hfgtgjnbvc3ujkl"
          ],
          "filters": [
            {}
          ],
          "reason": "<string>",
          "percentage_discount": 0.15
        },
        "minimum": {
          "minimum_amount": "<string>",
          "filters": [
            {
              "field": "<any>",
              "operator": "<any>",
              "values": "<any>"
            }
          ],
          "applies_to_price_ids": [
            "<string>"
          ]
        },
        "minimum_amount": "<string>",
        "maximum": {
          "maximum_amount": "<string>",
          "filters": [
            {
              "field": "<any>",
              "operator": "<any>",
              "values": "<any>"
            }
          ],
          "applies_to_price_ids": [
            "<string>"
          ]
        },
        "maximum_amount": "<string>"
      },
      "usage_customer_ids": [
        "<string>"
      ],
      "filter": "<string>"
    }
  ],
  "subtotal": "8.00",
  "invoice_date": "2022-05-01T07:00:00+00:00"
}

Authorizations

​
Authorization
string
header
required

API Keys can be issued in the Orb's web application.

Path Parameters

​
invoice_id
string
required

Body

application/json
​
payment_received_date
string<date>
required

A date string to specify the date of the payment.

Examples:

"2023-09-22"

​
external_id
string | null

An optional external ID to associate with the payment.

Examples:

"external_payment_id_123"

​
notes
string | null

An optional note to associate with the payment.

Response

OK

An Invoice is a fundamental billing entity, representing the request for payment for a single subscription. This includes a set of line items, which correspond to prices in the subscription's plan and can represent fixed recurring fees or usage-based fees. They are generated at the end of a billing period, or as the result of an action, such as a cancellation.

​
metadata
object
required

User specified key-value pairs for the resource. If not present, this defaults to an empty dictionary. Individual keys can be removed by setting the value to null, and the entire metadata mapping can be cleared by setting metadata to null.

​
voided_at
string<date-time> | null
required

If the invoice has a status of void, this gives a timestamp when the invoice was voided.

​
paid_at
string<date-time> | null
required

If the invoice has a status of paid, this gives a timestamp when the invoice was paid.

​
issued_at
string<date-time> | null
required

If the invoice has been issued, this will be the time it transitioned to issued (even if it is now in a different state.)

​
scheduled_issue_at
string<date-time> | null
required

If the invoice is in draft, this timestamp will reflect when the invoice is scheduled to be issued.

​
auto_collection
object
required
​
issue_failed_at
string<date-time> | null
required

If the invoice failed to issue, this will be the last time it failed to issue (even if it is now in a different state.)

​
sync_failed_at
string<date-time> | null
required

If the invoice failed to sync, this will be the last time an external invoicing provider sync was attempted. This field will always be null for invoices using Orb Invoicing.

​
payment_failed_at
string<date-time> | null
required

If payment was attempted on this invoice but failed, this will be the time of the most recent attempt.

​
payment_started_at
string<date-time> | null
required

If payment was attempted on this invoice, this will be the start time of the most recent attempt. This field is especially useful for delayed-notification payment mechanisms (like bank transfers), where payment can take 3 days or more.

​
amount_due
string
required

This is the final amount required to be charged to the customer and reflects the application of the customer balance to the total of the invoice.

Examples:

"8.00"

​
created_at
string<date-time>
required

The creation time of the resource in Orb.

Examples:

"2022-05-01T07:01:31+00:00"

​
currency
string
required

An ISO 4217 currency string or credits

Examples:

"USD"

​
customer
object
required
​
due_date
string<date-time> | null
required

When the invoice payment is due. The due date is null if the invoice is not yet finalized.

Examples:

"2022-05-30T07:00:00+00:00"

​
id
string
required
​
invoice_pdf
string | null
required

The link to download the PDF representation of the Invoice.

Examples:

"https://assets.withorb.com/invoice/rUHdhmg45vY45DX/qEAeuYePaphGMdFb"

​
invoice_number
string
required

Automatically generated invoice number to help track and reconcile invoices. Invoice numbers have a prefix such as RFOBWG. These can be sequential per account or customer.

Examples:

"JYEFHK-00001"

​
subscription
object | null
required
​
total
string
required

The total after any minimums and discounts have been applied.

Examples:

"8.00"

​
customer_balance_transactions
CustomerBalanceTransaction · object[]
required
​
status
enum<string>
required
Available options:
issued,
paid,
synced,
void,
draft
​
invoice_source
enum<string>
required
Available options:
subscription,
partial,
one_off
​
shipping_address
object | null
required
​
billing_address
object | null
required
​
hosted_invoice_url
string | null
required

A URL for the customer-facing invoice portal. This URL expires 30 days after the invoice's due date, or 60 days after being re-generated through the UI.

​
will_auto_issue
boolean
required

This is true if the invoice will be automatically issued in the future, and false otherwise.

​
eligible_to_issue_at
string<date-time> | null
required

If the invoice has a status of draft, this will be the time that the invoice will be eligible to be issued, otherwise it will be null. If auto-issue is true, the invoice will automatically begin issuing at this time.

​
customer_tax_id
object | null
required

Tax IDs are commonly required to be displayed on customer invoices, which are added to the headers of invoices.

Supported Tax ID Countries and Types

CountryTypeDescription
Albaniaal_tinAlbania Tax Identification Number
Andorraad_nrtAndorran NRT Number
Angolaao_tinAngola Tax Identification Number
Argentinaar_cuitArgentinian Tax ID Number
Armeniaam_tinArmenia Tax Identification Number
Arubaaw_tinAruba Tax Identification Number
Australiaau_abnAustralian Business Number (AU ABN)
Australiaau_arnAustralian Taxation Office Reference Number
Austriaeu_vatEuropean VAT Number
Azerbaijanaz_tinAzerbaijan Tax Identification Number
Bahamasbs_tinBahamas Tax Identification Number
Bahrainbh_vatBahraini VAT Number
Bangladeshbd_binBangladesh Business Identification Number
Barbadosbb_tinBarbados Tax Identification Number
Belarusby_tinBelarus TIN Number
Belgiumeu_vatEuropean VAT Number
Beninbj_ifuBenin Tax Identification Number (Identifiant Fiscal Unique)
Boliviabo_tinBolivian Tax ID
Bosnia and Herzegovinaba_tinBosnia and Herzegovina Tax Identification Number
Brazilbr_cnpjBrazilian CNPJ Number
Brazilbr_cpfBrazilian CPF Number
Bulgariabg_uicBulgaria Unified Identification Code
Bulgariaeu_vatEuropean VAT Number
Burkina Fasobf_ifuBurkina Faso Tax Identification Number (Numéro d'Identifiant Fiscal Unique)
Cambodiakh_tinCambodia Tax Identification Number
Camerooncm_niuCameroon Tax Identification Number (Numéro d'Identifiant fiscal Unique)
Canadaca_bnCanadian BN
Canadaca_gst_hstCanadian GST/HST Number
Canadaca_pst_bcCanadian PST Number (British Columbia)
Canadaca_pst_mbCanadian PST Number (Manitoba)
Canadaca_pst_skCanadian PST Number (Saskatchewan)
Canadaca_qstCanadian QST Number (Québec)
Cape Verdecv_nifCape Verde Tax Identification Number (Número de Identificação Fiscal)
Chilecl_tinChilean TIN
Chinacn_tinChinese Tax ID
Colombiaco_nitColombian NIT Number
Congo-Kinshasacd_nifCongo (DR) Tax Identification Number (Número de Identificação Fiscal)
Costa Ricacr_tinCosta Rican Tax ID
Croatiaeu_vatEuropean VAT Number
Croatiahr_oibCroatian Personal Identification Number (OIB)
Cypruseu_vatEuropean VAT Number
Czech Republiceu_vatEuropean VAT Number
Denmarkeu_vatEuropean VAT Number
Dominican Republicdo_rcnDominican RCN Number
Ecuadorec_rucEcuadorian RUC Number
Egypteg_tinEgyptian Tax Identification Number
El Salvadorsv_nitEl Salvadorian NIT Number
Estoniaeu_vatEuropean VAT Number
Ethiopiaet_tinEthiopia Tax Identification Number
European Unioneu_oss_vatEuropean One Stop Shop VAT Number for non-Union scheme
Finlandeu_vatEuropean VAT Number
Franceeu_vatEuropean VAT Number
Georgiage_vatGeorgian VAT
Germanyde_stnGerman Tax Number (Steuernummer)
Germanyeu_vatEuropean VAT Number
Greeceeu_vatEuropean VAT Number
Guineagn_nifGuinea Tax Identification Number (Número de Identificação Fiscal)
Hong Konghk_brHong Kong BR Number
Hungaryeu_vatEuropean VAT Number
Hungaryhu_tinHungary Tax Number (adószám)
Icelandis_vatIcelandic VAT
Indiain_gstIndian GST Number
Indonesiaid_npwpIndonesian NPWP Number
Irelandeu_vatEuropean VAT Number
Israelil_vatIsrael VAT
Italyeu_vatEuropean VAT Number
Japanjp_cnJapanese Corporate Number (Hōjin Bangō)
Japanjp_rnJapanese Registered Foreign Businesses' Registration Number (Tōroku Kokugai Jigyōsha no Tōroku Bangō)
Japanjp_trnJapanese Tax Registration Number (Tōroku Bangō)
Kazakhstankz_binKazakhstani Business Identification Number
Kenyake_pinKenya Revenue Authority Personal Identification Number
Kyrgyzstankg_tinKyrgyzstan Tax Identification Number
Laosla_tinLaos Tax Identification Number
Latviaeu_vatEuropean VAT Number
Liechtensteinli_uidLiechtensteinian UID Number
Liechtensteinli_vatLiechtenstein VAT Number
Lithuaniaeu_vatEuropean VAT Number
Luxembourgeu_vatEuropean VAT Number
Malaysiamy_frpMalaysian FRP Number
Malaysiamy_itnMalaysian ITN
Malaysiamy_sstMalaysian SST Number
Maltaeu_vatEuropean VAT Number
Mauritaniamr_nifMauritania Tax Identification Number (Número de Identificação Fiscal)
Mexicomx_rfcMexican RFC Number
Moldovamd_vatMoldova VAT Number
Montenegrome_pibMontenegro PIB Number
Moroccoma_vatMorocco VAT Number
Nepalnp_panNepal PAN Number
Netherlandseu_vatEuropean VAT Number
New Zealandnz_gstNew Zealand GST Number
Nigeriang_tinNigerian Tax Identification Number
North Macedoniamk_vatNorth Macedonia VAT Number
Northern Irelandeu_vatNorthern Ireland VAT Number
Norwayno_vatNorwegian VAT Number
Norwayno_voecNorwegian VAT on e-commerce Number
Omanom_vatOmani VAT Number
Perupe_rucPeruvian RUC Number
Philippinesph_tinPhilippines Tax Identification Number
Polandeu_vatEuropean VAT Number
Portugaleu_vatEuropean VAT Number
Romaniaeu_vatEuropean VAT Number
Romaniaro_tinRomanian Tax ID Number
Russiaru_innRussian INN
Russiaru_kppRussian KPP
Saudi Arabiasa_vatSaudi Arabia VAT
Senegalsn_nineaSenegal NINEA Number
Serbiars_pibSerbian PIB Number
Singaporesg_gstSingaporean GST
Singaporesg_uenSingaporean UEN
Slovakiaeu_vatEuropean VAT Number
Sloveniaeu_vatEuropean VAT Number
Sloveniasi_tinSlovenia Tax Number (davčna številka)
South Africaza_vatSouth African VAT Number
South Koreakr_brnKorean BRN
Spaines_cifSpanish NIF Number (previously Spanish CIF Number)
Spaineu_vatEuropean VAT Number
Surinamesr_finSuriname FIN Number
Swedeneu_vatEuropean VAT Number
Switzerlandch_uidSwitzerland UID Number
Switzerlandch_vatSwitzerland VAT Number
Taiwantw_vatTaiwanese VAT
Tajikistantj_tinTajikistan Tax Identification Number
Tanzaniatz_vatTanzania VAT Number
Thailandth_vatThai VAT
Turkeytr_tinTurkish Tax Identification Number
Ugandaug_tinUganda Tax Identification Number
Ukraineua_vatUkrainian VAT
United Arab Emiratesae_trnUnited Arab Emirates TRN
United Kingdomgb_vatUnited Kingdom VAT Number
United Statesus_einUnited States EIN
Uruguayuy_rucUruguayan RUC Number
Uzbekistanuz_tinUzbekistan TIN Number
Uzbekistanuz_vatUzbekistan VAT Number
Venezuelave_rifVenezuelan RIF Number
Vietnamvn_tinVietnamese Tax ID Number
Zambiazm_tinZambia Tax Identification Number
Zimbabwezw_tinZimbabwe Tax Identification Number
​
memo
string | null
required

Free-form text which is available on the invoice PDF and the Orb invoice portal.

​
credit_notes
CreditNoteSummary · object[]
required

A list of credit notes associated with the invoice

​
payment_attempts
PaymentAttempt · object[]
required

A list of payment attempts associated with the invoice

​
discount
any
required
deprecated

This field is deprecated in favor of discounts. If a discounts list is provided, the first discount in the list will be returned. If the list is empty, None will be returned.

​
discounts
Discounts · array
required
​
minimum
object | null
required
​
minimum_amount
string | null
required
​
maximum
object | null
required
​
maximum_amount
string | null
required
​
line_items
InvoiceLineItem · object[]
required

The breakdown of prices in this invoice.

​
subtotal
string
required

The total before any discounts and minimums are applied.

Examples:

"8.00"

​
invoice_date
string<date-time>
required

The scheduled date of the invoice

Examples:

"2022-05-01T07:00:00+00:00"