POST
/
invoices
curl --request POST \
  --url https://api.withorb.com/v1/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "metadata": {},
  "customer_id": "4khy3nwzktxv7",
  "external_customer_id": "external-customer-id",
  "currency": "USD",
  "memo": "An optional memo for my invoice.",
  "will_auto_issue": false,
  "invoice_date": "2023-09-22",
  "net_terms": 0,
  "line_items": [
    {
      "start_date": "2023-09-22",
      "end_date": "2023-09-22",
      "quantity": 1,
      "name": "Line Item Name",
      "item_id": "4khy3nwzktxv7",
      "model_type": "unit",
      "unit_config": {
        "unit_amount": "<string>"
      }
    }
  ],
  "discount": {
    "discount_type": "percentage",
    "applies_to_price_ids": [
      "h74gfhdjvn7ujokd",
      "7hfgtgjnbvc3ujkl"
    ],
    "reason": "<string>",
    "percentage_discount": 0.15
  }
}'
{
  "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>"
  },
  "discount": "<any>",
  "discounts": [
    {
      "discount_type": "percentage",
      "applies_to_price_ids": [
        "h74gfhdjvn7ujokd",
        "7hfgtgjnbvc3ujkl"
      ],
      "reason": "<string>",
      "percentage_discount": 0.15
    }
  ],
  "due_date": "2022-05-30T07:00:00+00:00",
  "id": "<string>",
  "invoice_pdf": "https://assets.withorb.com/invoice/rUHdhmg45vY45DX/qEAeuYePaphGMdFb",
  "invoice_number": "JYEFHK-00001",
  "minimum": {
    "minimum_amount": "<string>",
    "filters": [
      {
        "field": "price_id",
        "operator": "includes",
        "values": [
          "<string>"
        ]
      }
    ]
  },
  "minimum_amount": "<string>",
  "maximum": {
    "maximum_amount": "<string>",
    "filters": [
      {
        "field": "price_id",
        "operator": "includes",
        "values": [
          "<string>"
        ]
      }
    ]
  },
  "maximum_amount": "<string>",
  "line_items": [
    {
      "amount": "7.00",
      "discount": {
        "discount_type": "percentage",
        "applies_to_price_ids": [
          "h74gfhdjvn7ujokd",
          "7hfgtgjnbvc3ujkl"
        ],
        "reason": "<string>",
        "percentage_discount": 0.15
      },
      "end_date": "2022-02-01T08:00:00+00:00",
      "grouping": "<string>",
      "minimum": {
        "minimum_amount": "<string>",
        "filters": [
          {
            "field": "price_id",
            "operator": "includes",
            "values": [
              "<string>"
            ]
          }
        ]
      },
      "minimum_amount": "<string>",
      "maximum": {
        "maximum_amount": "<string>",
        "filters": [
          {
            "field": "price_id",
            "operator": "includes",
            "values": [
              "<string>"
            ]
          }
        ]
      },
      "maximum_amount": "<string>",
      "adjustments": [
        {
          "id": "<string>",
          "is_invoice_level": true,
          "filters": [
            {
              "field": "price_id",
              "operator": "includes",
              "values": [
                "<string>"
              ]
            }
          ],
          "reason": "<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": {
        "metadata": {},
        "id": "<string>",
        "name": "<string>",
        "external_price_id": "<string>",
        "price_type": "usage_price",
        "model_type": "unit",
        "created_at": "2023-11-07T05:31:56Z",
        "cadence": "one_time",
        "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,
        "item": {
          "id": "<string>",
          "name": "<string>"
        },
        "credit_allocation": {
          "currency": "<string>",
          "allows_rollover": true
        },
        "discount": {
          "discount_type": "percentage",
          "applies_to_price_ids": [
            "h74gfhdjvn7ujokd",
            "7hfgtgjnbvc3ujkl"
          ],
          "reason": "<string>",
          "percentage_discount": 0.15
        },
        "minimum": {
          "minimum_amount": "<string>",
          "filters": [
            {
              "field": "price_id",
              "operator": "includes",
              "values": [
                "<string>"
              ]
            }
          ]
        },
        "minimum_amount": "<string>",
        "maximum": {
          "maximum_amount": "<string>",
          "filters": [
            {
              "field": "price_id",
              "operator": "includes",
              "values": [
                "<string>"
              ]
            }
          ]
        },
        "maximum_amount": "<string>",
        "unit_config": {
          "unit_amount": "<string>"
        }
      },
      "usage_customer_ids": [
        "<string>"
      ],
      "filter": "<string>"
    }
  ],
  "subscription": {
    "id": "VDGsT23osdLb84KD"
  },
  "subtotal": "8.00",
  "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"
    }
  ],
  "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.

Body

application/json

Response

201
application/json

Created

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.