---
title: "Invoice created."
method: POST
path: "usage-billing.invoice.created"
tags: ["Invoices"]
---

# Invoice created.

`POST usage-billing.invoice.created` (webhook)

Webhook for invoice creation.

## Headers

- `paypal-transmission-id` string
- `paypal-transmission-time` string

## Payload

- object
  - `id` string, required: Unique identifier for the webhook event.
  - `create_time` string, date-time, required: Date and time in ISO 8601 format.
  - `event_version` string: Version of the event schema.
  - `summary` string: Brief description of the event.
  - `resource_version` string: Version of the resource schema.
  - `links` Link[]: HATEOAS links for the webhook event.
    - `href` string, uri, required: URL for the action.
    - `rel` string, required: Relation type of the link.
    - `method` string, required: HTTP method to use with the URL.
  - `resource_type` 'subscription-alert' | 'wallet' | 'wallet-transaction' | 'credit-note' | 'invoice' | 'subscription', required: Type of resource that triggered the webhook.
  - `event_type` 'USAGE-BILLING.SUBSCRIPTION-ALERT.TRIGGERED' | 'USAGE-BILLING.WALLET.CREATED' | 'USAGE-BILLING.WALLET.UPDATED' | 'USAGE-BILLING.WALLET.NET-BALANCE-DEPLETED' | 'USAGE-BILLING.WALLET.TERMINATED' | 'USAGE-BILLING.WALLET-TRANSACTION.CREATED' | 'USAGE-BILLING.WALLET-TRANSACTION.UPDATED' | 'USAGE-BILLING.CREDIT-NOTE.CREATED' | 'USAGE-BILLING.CREDIT-NOTE.REFUND.FAILED' | 'USAGE-BILLING.INVOICE.CREATED' | 'USAGE-BILLING.INVOICE.PAYMENT.OVERDUE' | 'USAGE-BILLING.INVOICE.PAYMENT.SUCCEEDED' | 'USAGE-BILLING.INVOICE.PAYMENT.FAILED' | 'USAGE-BILLING.SUBSCRIPTION.UPDATED' | 'USAGE-BILLING.SUBSCRIPTION.TERMINATED' | 'USAGE-BILLING.SUBSCRIPTION.TRIAL.ENDED', required: Type of event that occurred in webhooks.
  - `resource` InvoiceWithId, required
    - `id` string: The unique identifier of the invoice
    - `billing_entity_code` string: Unique code used to identify the billing entity. Must contain only alphanumeric characters, underscores, and hyphens.
    - `sequential_id` integer: Sequential ID of the invoice, unique within the billing entity.
    - `status` 'DRAFT' | 'FINALIZED', nullable: Status of the invoice
    - `payment_status` 'PENDING' | 'FAILED' | 'SUCCEEDED': Status of invoice payment
    - `amount` AmountWithBreakdown
      - `total_amount` Amount
        - `value` number, required: The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY).
        - `currency_code` string, required: Currency code in ISO 4217 format.
      - `breakdown` AmountBreakdown
        - `fees` Amount
          - `value` number, required: The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY).
          - `currency_code` string, required: Currency code in ISO 4217 format.
        - `credit_notes` Amount
          - `value` number, required: The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY).
          - `currency_code` string, required: Currency code in ISO 4217 format.
        - `sub_total_excluding_taxes` Amount
          - `value` number, required: The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY).
          - `currency_code` string, required: Currency code in ISO 4217 format.
        - `taxes` Amount
          - `value` number, required: The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY).
          - `currency_code` string, required: Currency code in ISO 4217 format.
        - `sub_total_including_taxes` Amount
          - `value` number, required: The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY).
          - `currency_code` string, required: Currency code in ISO 4217 format.
        - `prepaid_credit` Amount
          - `value` number, required: The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY).
          - `currency_code` string, required: Currency code in ISO 4217 format.
        - `progressive_billing_credit` Amount
          - `value` number, required: The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY).
          - `currency_code` string, required: Currency code in ISO 4217 format.
    - `fees` FeeObject[]
      - `id` string, uuid, nullable: Unique identifier assigned to the fee. This ID is exclusively and serves as a unique identifier for the fee's record.
      - `total_amount` Amount
        - `value` number, required: The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY).
        - `currency_code` string, required: Currency code in ISO 4217 format.
      - `name` string, nullable: The the name of the fee associated to any one of the charge, the credit, the subscription or the commitment
    - `due_date` string, date: Date in ISO 8601 format (YYYY-MM-DD).
    - `issued_date` string, date: Date in ISO 8601 format (YYYY-MM-DD).
    - `invoice_number` string: Invoice number, unique within the billing entity.
    - `version_number` string, number: Version number of the invoice, indicating the revision of the invoice.
    - `payment_overdue` boolean: Indicates whether the invoice payment is overdue.
    - `invoice_type` 'SUBSCRIPTION' | 'ONE_OFF' | 'CREDIT', nullable: Type of invoice
    - `customer` CustomerWithId: A customer represents an individual or organization that can be billed for services. It includes personal information, contact details, and metadata.
      - `name` string, required: Full name of the customer
      - `external_id` string, required: External identifier for the customer. Must contain only alphanumeric characters, underscores, and hyphens.
      - `email` string, required: The internationalized email address.
      - `billing_entity_code` string: Unique code used to identify the billing entity. Must contain only alphanumeric characters, underscores, and hyphens.
      - `address` Address: Address of the customer or party.
        - `line1` string: First line of the address.
        - `line2` string: Second line of the address (optional). This can include apartment, suite, or unit numbers.
        - `city` string: City of the customer or party.
        - `state` string: State or region of the customer or party.
        - `postal_code` string: Postal or ZIP code of the customer or party. Typically required for countries with a postal code or an equivalent.
        - `country` string: Country of the customer or party. Use ISO 3166-1 alpha-2 country codes.
      - `phone` string, phone: Primary phone number of the customer, including country code if available.
      - `payment_method_token` string: Token representing the customer's saved payment method in PayPal Vault.
      - `payment_method_type` 'CARD' | 'PAYPAL' | 'ACH_DEBIT' | 'APPLE_PAY': Type of payment method used (e.g., CARD, ACH_DEBIT)
      - `taxes` TaxResponse[]: List of tax entities configured for the customer.
        - `name` string, required: Name of the tax
        - `rate` string: The percentage rate of the tax applied to transactions. A decimal amount from 0.01 to 100.00 inclusive, always with exactly two decimal places, no leading zeros except 0.xx.
        - `description` string: Detailed description of the tax for internal reference
        - `code` string: Unique code used to identify the tax. Must contain only alphanumeric characters, underscores, and hyphens.
        - `id` string, uuid: Unique identifier of the tax
        - `created_at` string, date-time: The effective start date of the subscription; can be past, current, or future. Date must be provided in ISO 8601 format
      - `metadata` CustomerMetadata[]
        - `key` string, required: The metadata object key
        - `value` string, required: The metadata object value
        - `display_in_invoice` boolean, required: Determines whether the item or information should be displayed in the invoice. If set to true, the item or information will be included and visible in the generated invoice. If set to false, the item or information will be excluded and not displayed in the invoice.
      - `id` string
    - `billing_period` object[]
      - `subscription_id` string: Unique identifier for the subscription
      - `external_subscription_id` string: The subscription external unique identifier supplied by client.
      - `plan_id` string: Unique identifier for the plan
      - `payment_method_token` string: Token representing the customer's saved payment method in PayPal Vault.
      - `payment_method_type` 'CARD' | 'PAYPAL' | 'ACH_DEBIT' | 'APPLE_PAY': Type of payment method used (e.g., CARD, ACH_DEBIT)
      - `subscription_from_datetime` string, date-time: Date and time in ISO 8601 format.
      - `subscription_to_datetime` string, date-time: Date and time in ISO 8601 format.
      - `charges_from_datetime` string, date-time: Date and time in ISO 8601 format.
      - `charges_to_datetime` string, date-time: Date and time in ISO 8601 format.
      - `invoicing_reason` string: Reason for invoicing, e.g., 'subscription', 'usage', 'one-time charge'
    - `created_at` string, date-time: Date and time in ISO 8601 format.
    - `updated_at` string, date-time: Timestamp when the invoice was last updated
    - `applied_taxes` object[]
      - `id` string, uuid: Unique identifier of the applied tax.
      - `tax_id` string, uuid: Unique identifier of the tax.
      - `tax_name` string: Name of the tax.
      - `tax_code` string: Unique code used to identify the tax associated with the API request.
      - `tax_rate` number: The percentage rate of the tax
      - `tax_description` string: Internal description of the taxes
      - `amount` Amount
        - `value` number, required: The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY).
        - `currency_code` string, required: Currency code in ISO 4217 format.
      - `created_at` string, date-time: Date and time in ISO 8601 format.
      - `fees_amount` AmountNoCurrency
        - `value` number, required: The amount value in the corresponding currency unit (e.g., two decimals for USD, no decimals for JPY).

## Acknowledgement `204`

Return a 204 status to indicate that the data was received successfully.

---

[API](https://skmtc.dev/paypal/apis/usage-based-billing-api.md) - [All operations](https://skmtc.dev/paypal/apis/usage-based-billing-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paypal/apis/usage-based-billing-api/revisions/22fb46514ac4?raw)