Retrieve an invoice

curl --request GET \
  --url https://api.assembly.com/v1/invoices/{id} \
  --header 'X-API-KEY: <api-key>'

import requests

url = "https://api.assembly.com/v1/invoices/{id}"

headers = {"X-API-KEY": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};

fetch('https://api.assembly.com/v1/invoices/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.assembly.com/v1/invoices/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.assembly.com/v1/invoices/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-KEY", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.assembly.com/v1/invoices/{id}")
  .header("X-API-KEY", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.assembly.com/v1/invoices/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "address": {
    "addressLine1": "548 Market St",
    "addressLine2": "Suite 100",
    "city": "San Francisco",
    "country": "United States",
    "fullAddress": "548 Market St, San Francisco, CA 94105",
    "postalCode": "94105",
    "region": "California"
  },
  "amountPaid": 123,
  "attachmentKeys": [
    "<string>"
  ],
  "attachmentUrls": [
    "<string>"
  ],
  "billingReason": "manual",
  "clientId": "client_a1b2c3d4e5f6",
  "collectionMethod": "sendInvoice",
  "companyId": "company_a1b2c3d4e5f6",
  "createdAt": "<string>",
  "creatorId": "<string>",
  "currency": "usd",
  "data": "<string>",
  "daysUntilDue": 14,
  "dueDate": "2024-03-01T00:00:00Z",
  "entityType": "<string>",
  "fileKey": "<string>",
  "fileUrl": "<string>",
  "id": "<string>",
  "identityId": "<string>",
  "interval": "<string>",
  "latestRefundStatus": "succeeded",
  "lineItems": [
    {
      "amount": 5000,
      "description": "Onboarding setup fee",
      "id": "<string>",
      "priceId": "price_1a2b3c",
      "priceInterval": "month",
      "productId": "prod_1a2b3c",
      "quantity": 2,
      "type": "<string>"
    }
  ],
  "memo": "Thanks for your business",
  "number": "INV-0001",
  "object": "<string>",
  "origin": "internal",
  "paidManually": true,
  "payment": [
    {
      "amount": 10000,
      "brand": "Visa",
      "chargedAt": "2024-02-20T14:05:00Z",
      "createdAt": "<string>",
      "creatorId": "<string>",
      "data": "<string>",
      "declineCode": "insufficientFunds",
      "entityType": "PAYMENT",
      "fee": {
        "absorbedAmount": 0,
        "chargedAmount": 150,
        "isFeeAbsorbed": false,
        "items": [
          {
            "amount": 150,
            "type": "ccPercentage"
          }
        ],
        "totalAmount": 150
      },
      "feeAmount": {
        "paidByClient": 150,
        "paidByPlatform": 0
      },
      "id": "<string>",
      "identityId": "<string>",
      "intentId": "pi_3OabcdEFghIJklmn",
      "invoiceId": "550e8400-e29b-41d4-a716-446655440000",
      "last4Digits": "4242",
      "message": "The card has insufficient funds to complete the purchase.",
      "object": "<string>",
      "paymentMethod": "creditCard",
      "portalId": "a1b2c3d4",
      "previousAttributes": {},
      "ref": "<string>",
      "status": "succeeded",
      "stripeChargeId": "ch_3OabcdEFghIJklmn",
      "updatedAt": "<string>"
    }
  ],
  "paymentMethodPreferences": [
    {
      "feePaidByClient": true,
      "type": "creditCard"
    }
  ],
  "paymentPreferences": {
    "absorbTransactionFee": [],
    "paymentMethodTypes": []
  },
  "paymentSourceId": "<string>",
  "paymentSuccessDate": "2024-02-20T14:05:00Z",
  "portalId": "<string>",
  "previousAttributes": {},
  "quickBooksData": {
    "invoiceId": "<string>",
    "paymentId": "<string>"
  },
  "receiptKey": "<string>",
  "receiptNumber": "REC-0001",
  "receiptUrl": "<string>",
  "recipientId": "client_a1b2c3d4e5f6",
  "ref": "<string>",
  "sentDate": "2024-02-15T09:00:00Z",
  "sourcePaymentLinkId": "plink_a1b2c3d4e5f6",
  "status": "open",
  "subscription": {
    "additionalFields": {},
    "cancelledAt": "2024-02-20T14:05:00Z",
    "clientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "collectionMethod": "sendInvoice",
    "companyId": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
    "createdAt": "<string>",
    "creatorId": "<string>",
    "currency": "usd",
    "data": "<string>",
    "daysUntilDue": 30,
    "fields": {
      "absorbTransactionFees": true,
      "address": {
        "addressLine1": "548 Market St",
        "addressLine2": "Suite 100",
        "city": "San Francisco",
        "country": "United States",
        "fullAddress": "548 Market St, San Francisco, CA 94105",
        "postalCode": "94105",
        "region": "California"
      },
      "allowPaymentViaACH": true,
      "allowPaymentViaCC": true,
      "attachment": "<string>",
      "cancelledAt": "<string>",
      "clientUserId": "<string>",
      "collectionMethod": "<string>",
      "companyId": "<string>",
      "currency": "<string>",
      "daysUntilDue": 123,
      "forcePaused": true,
      "interval": "<string>",
      "lineItems": [
        {
          "description": "<string>",
          "id": "<string>",
          "priceId": "<string>",
          "productId": "<string>",
          "quantity": 123,
          "rate": 123
        }
      ],
      "memo": "<string>",
      "paymentPreferences": {
        "absorbTransactionFee": [],
        "paymentMethodTypes": []
      },
      "prorate": true,
      "purchaseFields": {},
      "reactivatedBy": "<string>",
      "resetBillingCycle": true,
      "scheduleEndDate": 123,
      "scheduleIterations": 123,
      "scheduleStartDate": 123,
      "taxPercentage": 123
    },
    "filteredListIndexPkey": "<string>",
    "forcePaused": false,
    "id": "<string>",
    "identityId": "<string>",
    "interval": "monthly",
    "intervalCount": 1,
    "lineItems": [
      {
        "amount": 5000,
        "description": "Onboarding setup fee",
        "id": "<string>",
        "priceId": "price_1a2b3c",
        "priceInterval": "month",
        "productId": "prod_1a2b3c",
        "quantity": 2,
        "type": "<string>"
      }
    ],
    "memo": "Monthly retainer",
    "object": "<string>",
    "paymentMethodPreferences": [
      {
        "feePaidByClient": true,
        "type": "creditCard"
      }
    ],
    "paymentSourceId": "card_1a2b3c",
    "previousAttributes": {},
    "recipientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "ref": "<string>",
    "status": "active",
    "taxPercentage": 8.25,
    "templateId": "a7c3e9f1-2b4d-4e6a-8c0f-1d2e3f4a5b6c",
    "updatedAt": "<string>"
  },
  "subscriptionId": "sub_a1b2c3d4e5f6",
  "taxAmount": 1275,
  "taxPercentage": 8.5,
  "templateId": "itmpl_a1b2c3d4e5f6",
  "total": 15000,
  "updatedAt": "<string>"
}

{
  "code": "<string>",
  "data": "<unknown>",
  "message": "<string>"
}

{
  "code": "<string>",
  "data": "<unknown>",
  "message": "<string>"
}

{
  "code": "<string>",
  "data": "<unknown>",
  "message": "<string>"
}

GET

invoices

{id}

Retrieve an invoice

curl --request GET \
  --url https://api.assembly.com/v1/invoices/{id} \
  --header 'X-API-KEY: <api-key>'

import requests

url = "https://api.assembly.com/v1/invoices/{id}"

headers = {"X-API-KEY": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};

fetch('https://api.assembly.com/v1/invoices/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.assembly.com/v1/invoices/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.assembly.com/v1/invoices/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-KEY", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.assembly.com/v1/invoices/{id}")
  .header("X-API-KEY", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.assembly.com/v1/invoices/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "address": {
    "addressLine1": "548 Market St",
    "addressLine2": "Suite 100",
    "city": "San Francisco",
    "country": "United States",
    "fullAddress": "548 Market St, San Francisco, CA 94105",
    "postalCode": "94105",
    "region": "California"
  },
  "amountPaid": 123,
  "attachmentKeys": [
    "<string>"
  ],
  "attachmentUrls": [
    "<string>"
  ],
  "billingReason": "manual",
  "clientId": "client_a1b2c3d4e5f6",
  "collectionMethod": "sendInvoice",
  "companyId": "company_a1b2c3d4e5f6",
  "createdAt": "<string>",
  "creatorId": "<string>",
  "currency": "usd",
  "data": "<string>",
  "daysUntilDue": 14,
  "dueDate": "2024-03-01T00:00:00Z",
  "entityType": "<string>",
  "fileKey": "<string>",
  "fileUrl": "<string>",
  "id": "<string>",
  "identityId": "<string>",
  "interval": "<string>",
  "latestRefundStatus": "succeeded",
  "lineItems": [
    {
      "amount": 5000,
      "description": "Onboarding setup fee",
      "id": "<string>",
      "priceId": "price_1a2b3c",
      "priceInterval": "month",
      "productId": "prod_1a2b3c",
      "quantity": 2,
      "type": "<string>"
    }
  ],
  "memo": "Thanks for your business",
  "number": "INV-0001",
  "object": "<string>",
  "origin": "internal",
  "paidManually": true,
  "payment": [
    {
      "amount": 10000,
      "brand": "Visa",
      "chargedAt": "2024-02-20T14:05:00Z",
      "createdAt": "<string>",
      "creatorId": "<string>",
      "data": "<string>",
      "declineCode": "insufficientFunds",
      "entityType": "PAYMENT",
      "fee": {
        "absorbedAmount": 0,
        "chargedAmount": 150,
        "isFeeAbsorbed": false,
        "items": [
          {
            "amount": 150,
            "type": "ccPercentage"
          }
        ],
        "totalAmount": 150
      },
      "feeAmount": {
        "paidByClient": 150,
        "paidByPlatform": 0
      },
      "id": "<string>",
      "identityId": "<string>",
      "intentId": "pi_3OabcdEFghIJklmn",
      "invoiceId": "550e8400-e29b-41d4-a716-446655440000",
      "last4Digits": "4242",
      "message": "The card has insufficient funds to complete the purchase.",
      "object": "<string>",
      "paymentMethod": "creditCard",
      "portalId": "a1b2c3d4",
      "previousAttributes": {},
      "ref": "<string>",
      "status": "succeeded",
      "stripeChargeId": "ch_3OabcdEFghIJklmn",
      "updatedAt": "<string>"
    }
  ],
  "paymentMethodPreferences": [
    {
      "feePaidByClient": true,
      "type": "creditCard"
    }
  ],
  "paymentPreferences": {
    "absorbTransactionFee": [],
    "paymentMethodTypes": []
  },
  "paymentSourceId": "<string>",
  "paymentSuccessDate": "2024-02-20T14:05:00Z",
  "portalId": "<string>",
  "previousAttributes": {},
  "quickBooksData": {
    "invoiceId": "<string>",
    "paymentId": "<string>"
  },
  "receiptKey": "<string>",
  "receiptNumber": "REC-0001",
  "receiptUrl": "<string>",
  "recipientId": "client_a1b2c3d4e5f6",
  "ref": "<string>",
  "sentDate": "2024-02-15T09:00:00Z",
  "sourcePaymentLinkId": "plink_a1b2c3d4e5f6",
  "status": "open",
  "subscription": {
    "additionalFields": {},
    "cancelledAt": "2024-02-20T14:05:00Z",
    "clientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "collectionMethod": "sendInvoice",
    "companyId": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
    "createdAt": "<string>",
    "creatorId": "<string>",
    "currency": "usd",
    "data": "<string>",
    "daysUntilDue": 30,
    "fields": {
      "absorbTransactionFees": true,
      "address": {
        "addressLine1": "548 Market St",
        "addressLine2": "Suite 100",
        "city": "San Francisco",
        "country": "United States",
        "fullAddress": "548 Market St, San Francisco, CA 94105",
        "postalCode": "94105",
        "region": "California"
      },
      "allowPaymentViaACH": true,
      "allowPaymentViaCC": true,
      "attachment": "<string>",
      "cancelledAt": "<string>",
      "clientUserId": "<string>",
      "collectionMethod": "<string>",
      "companyId": "<string>",
      "currency": "<string>",
      "daysUntilDue": 123,
      "forcePaused": true,
      "interval": "<string>",
      "lineItems": [
        {
          "description": "<string>",
          "id": "<string>",
          "priceId": "<string>",
          "productId": "<string>",
          "quantity": 123,
          "rate": 123
        }
      ],
      "memo": "<string>",
      "paymentPreferences": {
        "absorbTransactionFee": [],
        "paymentMethodTypes": []
      },
      "prorate": true,
      "purchaseFields": {},
      "reactivatedBy": "<string>",
      "resetBillingCycle": true,
      "scheduleEndDate": 123,
      "scheduleIterations": 123,
      "scheduleStartDate": 123,
      "taxPercentage": 123
    },
    "filteredListIndexPkey": "<string>",
    "forcePaused": false,
    "id": "<string>",
    "identityId": "<string>",
    "interval": "monthly",
    "intervalCount": 1,
    "lineItems": [
      {
        "amount": 5000,
        "description": "Onboarding setup fee",
        "id": "<string>",
        "priceId": "price_1a2b3c",
        "priceInterval": "month",
        "productId": "prod_1a2b3c",
        "quantity": 2,
        "type": "<string>"
      }
    ],
    "memo": "Monthly retainer",
    "object": "<string>",
    "paymentMethodPreferences": [
      {
        "feePaidByClient": true,
        "type": "creditCard"
      }
    ],
    "paymentSourceId": "card_1a2b3c",
    "previousAttributes": {},
    "recipientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "ref": "<string>",
    "status": "active",
    "taxPercentage": 8.25,
    "templateId": "a7c3e9f1-2b4d-4e6a-8c0f-1d2e3f4a5b6c",
    "updatedAt": "<string>"
  },
  "subscriptionId": "sub_a1b2c3d4e5f6",
  "taxAmount": 1275,
  "taxPercentage": 8.5,
  "templateId": "itmpl_a1b2c3d4e5f6",
  "total": 15000,
  "updatedAt": "<string>"
}

{
  "code": "<string>",
  "data": "<unknown>",
  "message": "<string>"
}

{
  "code": "<string>",
  "data": "<unknown>",
  "message": "<string>"
}

{
  "code": "<string>",
  "data": "<unknown>",
  "message": "<string>"
}

Authorizations

X-API-KEY

string

header

required

Path Parameters

string

required

Invoice ID

Response

address

object

Address stores the selected billing address from custom fields

Show child attributes

amountPaid

integer

AmountPaid is the amount paid so far in the smallest currency unit (e.g. cents).

attachmentKeys

string[]

AttachmentKeys are the storage keys of the invoice attachments.

attachmentUrls

string[]

AttachmentUrls are presigned download URLs for the invoice attachments.

billingReason

string

BillingReason describes why the invoice was created (e.g. manual, subscription cycle).

Example:

"manual"

clientId

string

ClientID is the ID of the client the invoice is billed to.

Example:

"client_a1b2c3d4e5f6"

collectionMethod

enum<string>

CollectionMethod controls how the invoice is collected.

Available options:

sendInvoice,

chargeAutomatically,

paymentLink

Example:

"sendInvoice"

companyId

string

CompanyID is the ID of the company the invoice is billed to.

Example:

"company_a1b2c3d4e5f6"

createdAt

string

creatorId

string

currency

string

Currency is the ISO 4217 currency code the invoice is denominated in.

Example:

"usd"

data

string

daysUntilDue

integer

DaysUntilDue is the number of days from issuance until the invoice is due.

Example:

14

dueDate

string<date-time> | null

DueDate is the RFC 3339 timestamp by which the invoice must be paid.

Example:

"2024-03-01T00:00:00Z"

entityType

string

ObjectType is the internal entity type discriminator.

fileKey

string

FileKey is the storage key of the invoice PDF.

fileUrl

string

FileUrl is the presigned download URL for the invoice PDF.

string

identityId

string

interval

string

Property copied from subscription when creating invoice We need this value when we have to show line items descriptions (Format "Item (at US$621.00 / month)") on invoice details for subscriptions invoices. We can fetch this directly from subscription at that time, but we delete subscriptions when we delete the recipient (client/company). For deleted recipients we still show invoices which were paid in the past. So we need to store this value here to show line items descriptions for invoices even if subscriptions are deleted.

invoiceCreationStatus

enum<string>

Available options:

ephemeral,

pending,

created

latestRefundStatus

enum<string>

LatestRefundStatus is the status of the most recent refund issued against the invoice, when any.

Available options:

pending,

succeeded,

failed

Example:

"succeeded"

lineItems

object[]

LineItems are the priced line items that make up the invoice.

Show child attributes

memo

string

Memo is an optional note shown to the recipient on the invoice.

Example:

"Thanks for your business"

number

string

Number is the human-readable invoice number.

Example:

"INV-0001"

object

string

origin

enum<string>

Origin indicates how the invoice was created.

Available options:

internal,

payment_link,

product_store

Example:

"internal"

paidManually

boolean

payment

object[]

represents the successful payments only

Show child attributes

paymentMethodPreferences

object[]

field is only used for platform api and should not be used anywhere else on FE/BE

Show child attributes

paymentPreferences

object

fields is used for BE/FE only

Show child attributes

paymentSourceId

string

paymentSuccessDate

string<date-time>

PaymentSuccessDate is the RFC 3339 timestamp at which payment succeeded; absent until paid.

Example:

"2024-02-20T14:05:00Z"

portalId

string

PortalID is the ID of the portal the invoice belongs to.

previousAttributes

object

quickBooksData

object

Show child attributes

receiptKey

string

receiptNumber

string

ReceiptNumber is the human-readable receipt number, set once the invoice is paid.

Example:

"REC-0001"

receiptUrl

string

ReceiptUrl is the presigned download URL for the receipt PDF.

recipientId

string

Deprecated: use ClientID and CompanyID instead

Example:

"client_a1b2c3d4e5f6"

ref

string

sentDate

string<date-time> | null

SentDate is the RFC 3339 timestamp at which the invoice was sent to the recipient.

Example:

"2024-02-15T09:00:00Z"

sourcePaymentLinkId

string

SourcePaymentLinkId is the ID of the payment link that produced this invoice, when applicable.

Example:

"plink_a1b2c3d4e5f6"

status

enum<string>

Status is the current lifecycle state of the invoice.

Available options:

draft,

open,

void,

paid,

processing

Example:

"open"

subscription

object

Subscription is populated from search results when subscriptionId is present (not persisted)

Show child attributes

subscriptionId

string

SubscriptionID is the ID of the subscription that generated this invoice, when applicable.

Example:

"sub_a1b2c3d4e5f6"

taxAmount

integer

TaxAmount is the computed tax in the smallest currency unit (e.g. cents).

Example:

1275

taxPercentage

number | null

TaxPercentage is the tax rate applied to the invoice, expressed as a percentage.

Example:

8.5

templateId

string

TemplateID is the ID of the invoice template the invoice was created from, when applicable.

Example:

"itmpl_a1b2c3d4e5f6"

total

integer

Total is the invoice total in the smallest currency unit (e.g. cents).

Example:

15000

updatedAt

string

Invoices List invoices

⌘I

Getting started

Webhooks

Core Resources

CRM

Messaging

Billing

Files

Contracts

Forms

Tasks

Token

Others

Retrieve an invoice

Authorizations

Path Parameters

Response