Managing Invoices

This guide shows how to list, retrieve, and act on invoices via the Oyster API. For background on how invoicing works in Oyster, see Invoicing at Oyster.

Note for Reseller partners using the API - you will need to use the X-Oyster-Customer-Id header for relevant calls. For more information, see the Reseller guide to using the Oyster API.

1. List invoices

Use the Retrieve all invoices endpoint to filter and list invoices. Handy for getting invoice IDs or reference codes for later calls, and for finding payment IDs to use with Payments endpoints.

Filter by multiple criteria, including dates, types, and statuses.
Retrieve general information from all the invoices: ID/reference code, type, status, amounts, and payments.

Example request

curl --request GET \
  --url /v1/invoices \
  --header 'accept: application/json'

Response

{
  "data": [
    {
      "id": "Face786a",
      "referenceCode": "OY-IMPA-ANNA-B7875a51-27b",
      "type": "MANUAL",
      "status": "WAITING_APPROVAL",
      "payrollMonth": "",
      "payrollYear": "",
      "issueDate": "2022-10-15",
      "dueDate": "2022-10-18",
      "amount": { "decimal": "700.71", "currencyCode": "USD" },
      "charge": {
        "id": "J7008331",
        "status": "PENDING",
        "amount": { "decimal": "700.71", "currencyCode": "USD" },
        "amountDue": { "decimal": "700.71", "currencyCode": "USD" }
      },
      "payout": { "id": "L17d469d", "status": "NOT_INITIATED", "amount": { "decimal": "700.71", "currencyCode": "USD" } }
    },
    {
      "id": "Dfde14f8",
      "referenceCode": "OY-IMPA-ANNA-B7875a51-142",
      "type": "MANUAL",
      "status": "WAITING_APPROVAL",
      "payrollMonth": "",
      "payrollYear": "",
      "issueDate": "2022-10-15",
      "dueDate": "2022-10-18",
      "amount": { "decimal": "195.85", "currencyCode": "USD" },
      "charge": {
        "id": "F5cbaf60",
        "status": "PENDING",
        "amount": { "decimal": "195.85", "currencyCode": "USD" },
        "amountDue": { "decimal": "195.85", "currencyCode": "USD" }
      },
      "payout": { "id": "H852c32d", "status": "NOT_INITIATED", "amount": { "decimal": "195.85", "currencyCode": "USD" } }
    },
    {
      "id": "Ba234d31",
      "referenceCode": "OY-IMPA-ANNA-B7875a51-05e",
      "type": "MANUAL",
      "status": "WAITING_APPROVAL",
      "payrollMonth": "",
      "payrollYear": "",
      "issueDate": "2022-10-15",
      "dueDate": "2022-10-18",
      "amount": { "decimal": "490.34", "currencyCode": "USD" },
      "charge": {
        "id": "B1277a59",
        "status": "PENDING",
        "amount": { "decimal": "490.34", "currencyCode": "USD" },
        "amountDue": { "decimal": "490.34", "currencyCode": "USD" }
      },
      "payout": { "id": "De0dc77c", "status": "NOT_INITIATED", "amount": { "decimal": "490.34", "currencyCode": "USD" } }
    }
  ],
  "meta": {
    "items": 100,
    "count": 3,
    "page": 1,
    "pages": 1,
    "firstUrl": "/v0.1/invoices?perPage=100&payrollPeriodFrom=&payrollPeriodTo=&issueDateFrom=&issueDateTo=&page=1",
    "lastUrl": "/v0.1/invoices?perPage=100&payrollPeriodFrom=&payrollPeriodTo=&issueDateFrom=&issueDateTo=&page=1",
    "pageUrl": "/v0.1/invoices?perPage=100&payrollPeriodFrom=&payrollPeriodTo=&issueDateFrom=&issueDateTo=&page=1",
    "nextUrl": "/v0.1/invoices?perPage=100&payrollPeriodFrom=&payrollPeriodTo=&issueDateFrom=&issueDateTo=&page=",
    "prevUrl": "/v0.1/invoices?perPage=100&payrollPeriodFrom=&payrollPeriodTo=&issueDateFrom=&issueDateTo=&page="
  }
}

2. Retrieve a single invoice

Use the Retrieve an invoice endpoint to get the complete details of one invoice by ID or reference code.

Retrieve complete information from that invoice, such as dates, amounts, files, line items, applied credit notes and payments.

Example request

curl --request GET \
  --url /v1/invoices/{invoiceId|referenceCode} \
  --header 'accept: application/json'

Response

{
  "data": {
    "id": "Ba234d31",
    "referenceCode": "OY-IMPA-ANNA-B7875a51-247",
    "type": "MANUAL",
    "status": "WAITING_APPROVAL",
    "payrollMonth": "10",
    "payrollYear": "2022",
    "issueDate": "2022-10-15",
    "dueDate": "2022-10-18",
    "amount": { "decimal": "952.89", "currencyCode": "USD" },
    "taxPercentage": null,
    "taxAmount": { "decimal": "0.00", "currencyCode": "USD" },
    "files": {
      "document": { "title": "file", "url": "https://example.com/file.pdf", "contentType": "application/pdf" },
      "breakdown": { "title": "supporting_file", "url": null, "contentType": null }
    },
    "lineItems": [
      {
        "description": "Quod inventore ducimus. Asperiores rem qui. Qui est sint.",
        "quantity": 3,
        "unitPrice": { "decimal": "278.38", "currencyCode": "USD" },
        "amount": { "decimal": "835.14", "currencyCode": "USD" }
      },
      {
        "description": "Repudiandae tempora in. Natus atque voluptatibus. Aperiam omnis iure.",
        "quantity": 8,
        "unitPrice": { "decimal": "650.15", "currencyCode": "USD" },
        "amount": { "decimal": "5201.20", "currencyCode": "USD" }
      }
    ],
    "appliedCredit": [
      {
        "referenceCode": "OY-IMPA-ANNA-D8cac3f5-13b0d0-CN",
        "appliedAt": "2022-10-15T12:34:56Z",
        "amount": { "decimal": "1000.00", "currencyCode": "USD" }
      }
    ],
    "charge": {
      "id": "B1277a59",
      "status": "PENDING",
      "amount": { "decimal": "952.89", "currencyCode": "USD" },
      "amountDue": { "decimal": "952.89", "currencyCode": "USD" }
    },
    "payout": null
  }
}

3. Retrieve invoice line items

For Prefunding, Settlement, and Deposit invoices, the Retrieve invoice breakdown endpoint returns payroll components for each engagement on the invoice. Retrieve details by either the invoiceId or the referenceCode.

Settlement invoices return three amounts per component using the same logic as the breakdown file: SETTLEMENT = ACTUAL - PREFUNDING.

Example request

curl --request GET \
  --url /v1/invoices/{invoiceId|referenceCode}/line_items \
  --header 'accept: application/json'

Response (Settlement)

{
  "data": [
    {
      "engagementId": "CtAtP7ts",
      "engagementName": "C",
      "region": "United Kingdom of Great Britain and Northern Ireland",
      "startDate": "2022-08-15",
      "terminationDate": "2022-10-14",
      "serviceMonth": "2022-10",
      "cutoffDate": "2022-10-06",
      "fxRate": { "from": "PLN", "to": "EUR", "rate": "0.25" },
      "total": { "decimal": "-352.50", "currencyCode": "EUR" },
      "components": [
        {
          "type": "Wellbeing",
          "amounts": [
            { "type": "PREFUNDING", "amount": { "decimal": "100.00", "currencyCode": "PLN" } },
            { "type": "ACTUAL", "amount": { "decimal": "240.00", "currencyCode": "PLN" } },
            { "type": "SETTLEMENT", "amount": { "decimal": "140.00", "currencyCode": "PLN" } }
          ]
        }
      ]
    },
    {
      "engagementId": "ue213VVh",
      "engagementName": "B",
      "region": "United Kingdom of Great Britain and Northern Ireland",
      "startDate": "2022-10-14",
      "terminationDate": null,
      "serviceMonth": "2022-10",
      "cutoffDate": "2022-10-06",
      "fxRate": { "from": "PLN", "to": "EUR", "rate": "0.25" },
      "total": { "decimal": "-352.50", "currencyCode": "EUR" },
      "components": [
        {
          "type": "Wellbeing",
          "amounts": [
            { "type": "PREFUNDING", "amount": { "decimal": "100.00", "currencyCode": "PLN" } },
            { "type": "ACTUAL", "amount": { "decimal": "240.00", "currencyCode": "PLN" } },
            { "type": "SETTLEMENT", "amount": { "decimal": "140.00", "currencyCode": "PLN" } }
          ]
        }
      ]
    },
    {
      "engagementId": "Lu5epoMU",
      "engagementName": "Treasa Bogan Jr.",
      "region": "Poland",
      "startDate": "2022-08-15",
      "terminationDate": "2022-12-31",
      "serviceMonth": "2022-10",
      "cutoffDate": "2022-10-11",
      "fxRate": { "from": "PLN", "to": "EUR", "rate": "0.25" },
      "total": { "decimal": "-352.50", "currencyCode": "EUR" },
      "components": [
        {
          "type": "Wellbeing",
          "amounts": [
            { "type": "PREFUNDING", "amount": { "decimal": "100.00", "currencyCode": "PLN" } },
            { "type": "ACTUAL", "amount": { "decimal": "240.00", "currencyCode": "PLN" } },
            { "type": "SETTLEMENT", "amount": { "decimal": "140.00", "currencyCode": "PLN" } }
          ]
        }
      ]
    }
  ],
  "meta": {
    "items": 100,
    "count": 3,
    "page": 1,
    "pages": 1,
    "firstUrl": "/v0.1/invoices/Ba234d31/line_items?page=1&perPage=100",
    "lastUrl": "/v0.1/invoices/Ba234d31/line_items?page=1&perPage=100",
    "pageUrl": "/v0.1/invoices/Ba234d31/line_items?page=1&perPage=100",
    "nextUrl": "/v0.1/invoices/Ba234d31/line_items?page=&perPage=100",
    "prevUrl": "/v0.1/invoices/Ba234d31/line_items?page=&perPage=100"
  }
}

4. Approve an invoice

Approve an invoice for payment using the Approve invoice endpoint. Invoices are automatically approved on the due date if not approved earlier. Retrieve details by either the invoiceId or the referenceCode.

Example request

curl --request POST \
  --url /v1/invoices/{invoiceId|referenceCode}/approve \
  --header 'accept: application/json'

Error response (422)

{
  "errors": [
    { "message": "The invoice is not in the right state to be approved" }
  ]
}

5. Dispute an invoice

Dispute an invoice you disagree with by using the Dispute invoice endpoint. Provide a reason for the dispute.

Example request

curl --request POST \
  --url /v1/invoices/{invoiceId|referenceCode}/dispute \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "reason": "Invalid invoice"
  }'

Example error response (422)

{
  "errors": [
    { "message": "The invoice state or type can not be disputed" }
  ]
}