invoices

Creates, updates, deletes, gets or lists an invoices resource.

Overview

Name	invoices
Type	Resource
Id	vercel.marketplace.invoices

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
external_id	string	Partner-supplied Invoice ID, if applicable. (wire: externalId)
invoice_id	string	Vercel Marketplace Invoice ID. (wire: invoiceId)
created	string	System creation date. ISO 8601 timestamp.
discounts	array	Invoice discounts.
invoice_date	string	Invoice date. ISO 8601 timestamp. (wire: invoiceDate)
invoice_number	string	User-readable invoice number. (wire: invoiceNumber)
items	array	Invoice items.
memo	string	Additional memo for the invoice.
paid_at	string	Moment the invoice was paid. ISO 8601 timestamp. (wire: paidAt)
period	object	Subscription period for this billing cycle. ISO 8601 timestamps.
refund_reason	string	The reason for refund. Only applicable for states "refunded" or "refund_request". (wire: refundReason)
refund_total	string	Refund amount. Only applicable for states "refunded" or "refund_request". A dollar-based decimal string. (wire: refundTotal)
refunded_at	string	Most recent moment the invoice was refunded. ISO 8601 timestamp. (wire: refundedAt)
state	string	Invoice state. (draft, invoiced, notpaid, overdue, paid, pending, refund_requested, refunded, scheduled)
test	boolean	Whether the invoice is in the testmode (no real transaction created). (false, true)
total	string	Invoice total amount. A dollar-based decimal string.
updated	string	System update date. ISO 8601 timestamp.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	integration_configuration_id, invoice_id		Get Invoice details and status for a given invoice ID.<br /> <br /> See [Billing Events with Webhooks documentation](https:​//vercel.com/docs/integrations/create-integration/marketplace-api#working-with-billing-events-through-webhooks) on how to receive invoice events. This endpoint is used to retrieve the invoice details.
create	insert	integration_configuration_id, invoice_date, period, items		This endpoint allows the partner to submit an invoice to Vercel. The invoice is created in Vercel's billing system and sent to the customer. Depending on the type of billing plan, the invoice can be sent at a time of signup, at the start of the billing period, or at the end of the billing period.<br /> <br /> Use the credentials.access_token we provided in the [Upsert Installation](#upsert-installation) body to authorize this request. <br /> There are several limitations to the invoice submission:<br /> <br /> 1. A resource can only be billed once per the billing period and the billing plan.<br /> 2. The billing plan used to bill the resource must have been active for this resource during the billing period.<br /> 3. The billing plan used must be a subscription plan.<br /> 4. The interim usage data must be sent hourly for all types of subscriptions. See [Send subscription billing and usage data](#send-subscription-billing-and-usage-data) API on how to send interim billing and usage data.<br /> 5. If provided, externalId must be unique for the installation.<br />
update	exec	integration_configuration_id, invoice_id, action, reason, total		This endpoint allows the partner to request a refund for an invoice to Vercel. The invoice is created using the [Submit Invoice API](#submit-invoice-api).

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
integration_configuration_id	string
invoice_id	string

SELECT examples

get

Get Invoice details and status for a given invoice ID.<br /> <br /> See [Billing Events with Webhooks documentation](https:​//vercel.com/docs/integrations/create-integration/marketplace-api#working-with-billing-events-through-webhooks) on how to receive invoice events. This endpoint is used to retrieve the invoice details.

SELECT
external_id,
invoice_id,
created,
discounts,
invoice_date,
invoice_number,
items,
memo,
paid_at,
period,
refund_reason,
refund_total,
refunded_at,
state,
test,
total,
updated
FROM vercel.marketplace.invoices
WHERE integration_configuration_id = '{{ integration_configuration_id }}' -- required
AND invoice_id = '{{ invoice_id }}' -- required
;

INSERT examples

create

This endpoint allows the partner to submit an invoice to Vercel. The invoice is created in Vercel's billing system and sent to the customer. Depending on the type of billing plan, the invoice can be sent at a time of signup, at the start of the billing period, or at the end of the billing period.<br /> <br /> Use the credentials.access_token we provided in the [Upsert Installation](#upsert-installation) body to authorize this request. <br /> There are several limitations to the invoice submission:<br /> <br /> 1. A resource can only be billed once per the billing period and the billing plan.<br /> 2. The billing plan used to bill the resource must have been active for this resource during the billing period.<br /> 3. The billing plan used must be a subscription plan.<br /> 4. The interim usage data must be sent hourly for all types of subscriptions. See [Send subscription billing and usage data](#send-subscription-billing-and-usage-data) API on how to send interim billing and usage data.<br /> 5. If provided, externalId must be unique for the installation.<br />

INSERT INTO vercel.marketplace.invoices (
external_id,
invoice_date,
memo,
period,
items,
discounts,
final,
test,
integration_configuration_id
)
SELECT 
'{{ external_id }}',
'{{ invoice_date }}' /* required */,
'{{ memo }}',
'{{ period }}' /* required */,
'{{ items }}' /* required */,
'{{ discounts }}',
{{ final }},
'{{ test }}',
'{{ integration_configuration_id }}'
RETURNING
invoice_id,
test,
validation_errors
;

Manifest

# Description fields are for documentation purposes
- name: invoices
props:
  - name: integration_configuration_id
    value: "{{ integration_configuration_id }}"
    description: Required parameter for the invoices resource.
  - name: external_id
    value: "{{ external_id }}"
    description: |
      Partner-provided invoice identifier. If provided, it must be unique for this installation.
  - name: invoice_date
    value: "{{ invoice_date }}"
    description: |
      Invoice date. Must be within the period's start and end.
  - name: memo
    value: "{{ memo }}"
    description: |
      Additional memo for the invoice.
  - name: period
    description: |
      Subscription period for this billing cycle.
    value:
      start: "{{ start }}"
      end: "{{ end }}"
  - name: items
    value:
      - resourceId: "{{ resourceId }}"
        billingPlanId: "{{ billingPlanId }}"
        start: "{{ start }}"
        end: "{{ end }}"
        name: "{{ name }}"
        details: "{{ details }}"
        price: "{{ price }}"
        quantity: {{ quantity }}
        units: "{{ units }}"
        total: "{{ total }}"
  - name: discounts
    value:
      - resourceId: "{{ resourceId }}"
        billingPlanId: "{{ billingPlanId }}"
        start: "{{ start }}"
        end: "{{ end }}"
        name: "{{ name }}"
        details: "{{ details }}"
        amount: "{{ amount }}"
  - name: final
    value: {{ final }}
    description: |
      Set this to `true` if this is the final invoice for the installation. Can only be set when the installation is pending deletion.
  - name: test
    description: |
      Test mode
    value:
      validate: {{ validate }}
      result: "{{ result }}"

Lifecycle Methods

EXEC variables use wire (API) names.

update

This endpoint allows the partner to request a refund for an invoice to Vercel. The invoice is created using the Submit Invoice API.

EXEC vercel.marketplace.invoices.update 
@integration_configuration_id='{{ integration_configuration_id }}' --required, 
@invoice_id='{{ invoice_id }}' --required 
@@json=
'{
"action": "{{ action }}", 
"reason": "{{ reason }}", 
"total": "{{ total }}"
}'
;