Invoices

Overview of the Invoice resource and associated endpoints.

8 minute read

IMPORTANT

Sellers building integrations into Marketplacer should only use the current GraphQL-based Seller API, and not this (REST-based) API.

All future developments, including new features will be added to the the GraphQL-based Seller API only, more details on this API can be found here

Invoices track a collection of items bought from a store in a single transaction. Invoices are also grouped further by a delivery type. For instance, if someone buys a bike which is “Click and Collect” and a helmet which is “Buy Online” in the same order and for the same retailer, these will be split up into two invoices for the one retailer.

Invoices have many line items which represent the amount of a particular advert purchased in the invoice.

Invoices have many shipments which represent the individual shipments that were dispatched to a customer (including shipment tracking number and carrier).

Invoices can transition through the following statuses:

Invoice Transitions

An invoice can be marked as “Ready” and then “Collected” only if the invoice is a “Click and Collect” invoice. Similarly, it can only be marked as “Sent” if it is a “Buy Online” invoice.

An invoice can also be marked as “Partially Sent”. This state, however, can only be achieved by managing via Shipments endpoint.

An invoice will have both a “created_at” timestamp and a “paid_at” timestamp. You can only retrieve invoices after they have been paid, so you should use the “paid_at” timestamp as your canonical timestamp for the invoice.

Listing invoices

This endpoint returns a paginated list of invoices.

Request

GET /api/v2/client/invoices

You may optionally choose to retrieve invoices which were paid since a certain time:

GET /api/v2/client/invoices?since=2015-11-09T00:00:00Z

Or paid before a certain time:

GET /api/v2/client/invoices?until=2015-11-10T00:00:00Z

Or updated since a certain time:

GET /api/v2/client/invoices?updated_since=2015-11-10T00:00:00Z

Or updated before a certain time:

GET /api/v2/client/invoices?updated_before=2015-11-10T00:00:00Z

Or which have a certain status:

GET /api/v2/client/invoices?status=sent

Valid statuses are “paid”, “sent”, “partially_sent”, “ready” “collected”.

Because invoices can be partially shipped, partially returned and partially refunded now, the invoice status field is not as useful as it used to be. We recommend against using the invoice status where possible.

You can also combine the terms as follows:

GET /api/v2/client/invoices?updated_since=2015-11-10T00:00:00Z&status=sent

Response

Status: 200 OK

{
  "data": [
    {
      "type": "invoices",
      "id": "10112",
      "attributes": {
        "postage": "0.0",
        "postage_before_discount": "0.0",
        "paid_at": "2020-11-11T14:49:18.000+11:00",
        "status": "sent",
        "delivery_type": "buy_online",
        "ready_at": "2020-11-12T14:49:18.000+11:00",
        "collected_at": "2020-13-11T14:49:18.000+11:00",
        "subtotal": "100.0",
        "discount": "0.0",
        "total": "100.0",
        "tax_on_postage": "0.0",
        "tax_total": "9.09",
        "created_at": "2020-11-11T14:49:13.000+11:00",
        "tax_inclusive": true,
        "message_to_seller": "",
        "seller_id": 78,
        "postage_tracking": "33PKP0004327",
        "postage_carrier": "Australia Post",
        "external_id": "123abc",
        "metadata": [
          {
            "key": "SomeKey",
            "value": "Some Value"
          }
        ]
      }
    }
  ]
}

Viewing Additional Data

As a default, when returning a collection of Invoices, the payload for each invoice is kept to a standard set of attributes. There may be instances however when you wish to include additional response data for each invoice. You can do this by appending any or all of the following query string parameters to your request:

Parameter	Additional Information
customer	Will return both the customer details along with the customer billing details. E.g. `first_name`, `surname`, `email_address` etc
line_items	Will return the purchased line items on the invoice
order	Will return any external ids associated with the parent Order. IMPORTANT: There is additional configuration required by the Operator of the marketplace before this attribute can be used / exposed. Refer to the section below.

Metadata

If metadata has been added to the Invoice, this will be presented without the need to supply any further parameters, see above example payload.

Return line_items and customer data

GET /api/v2/client/invoices?include=line_items,customer

Returning External Order Ids

You can elect to pass an order query string parameter when both returning a collection of invoices or when returning an individual invoice. For this data to be returned however, the Marketplacer Operator has to explicitly permit the exposure of the External Ids that they wish to be accessible on an invoice. The reason for this is that an Order is a Marketplace-wide object and as such its attributes are not usually exposed to individual sellers. Please contact the Operator of your Marketplace if you require this data to be exposed.

Showing an Individual Invoice

This endpoint will show an invoice’s information and includes the invoices line items as well as shipments by default.

Request

GET /api/v2/client/invoices/1

Response

Status: 200 OK

{
  "links": {
    "self": "https://bikeexchange.com.au/api/v2/client/invoices/1"
  },
  "data": {
    "id": 1,
    "type": "invoices",
    "attributes": {
      "postage": "10.0",
      "paid_at": "2022-11-15T15:10:35+11:00",
      "status": "paid",
      "delivery_type": "click_and_collect",
      "ready_at": null,
      "collected_at": null,
      "subtotal": "110.0",
      "discount": "10",
      "total": "100",
      "tax_total": "0.0",
      "created_at": "2022-11-15T15:10:35+11:00",
      "tax_inclusive": true,
      "message_to_seller": "",
      "expected_delivery_date": "2022-11-19",
      "expected_delivery_slot": "Morning",
      "seller_id": 2
    },
    "relationships": {
      "line_items": {
        "data": [
          {
            "type": "line_items",
            "id": 1
          }
        ]
      },
      "shipments": {
        "data": [
          {
            "type": "shipments",
            "id": 1
          }
        ]
      },
      "customer": {
        "data": {
          "type": "customers",
          "id": "customer"
        }
      },
      "billing_customer": {
        "data": {
          "type": "customers",
          "id": "billing_customer"
        }
      }
    }
  },
  "included": [
    {
      "id": 1,
      "type": "line_items",
      "attributes": {
        "price": "100.0",
        "status": "allocated",
        "subtotal": "100.",
        "tax_total": "0.0",
        "original_tax_rate": null,
        "total": "100.0",
        "quantity": 1,
        "taxon_name": "Hybrid Bikes",
        "brand_name": "Giant",
        "advert_name": "Giant Cypress DX",
        "advert_external_id": "ABC123",
        "variant_name": "Navy Blue / Medium",
        "variant_sku": null,
        "variant_barcode": "08717611735314",
        "variant_external_id": "DEF123"
      }
    },
    {
      "id": "customer",
      "type": "customers",
      "attributes": {
        "first_name": "Test",
        "surname": "User",
        "company_name": "Acme Pty Ltd",
        "email_address": "test@example.com",
        "phone": "0491570156",
        "address": "1 Example Road",
        "city": "Melbourne",
        "state": "Victoria",
        "postcode": "3000",
        "country": "Australia"
      }
    },
    {
      "id": "billing_customer",
      "type": "customers",
      "attributes": {
        "first_name": "Test",
        "surname": "User",
        "company_name": "Acme Pty Ltd",
        "email_address": "test+billing@example.com",
        "phone": "0491570156",
        "address": "1 Example Road",
        "city": "Melbourne",
        "state": "Victoria",
        "postcode": "3000",
        "country": "Australia"
      }
    },
    {
      "id": 1,
      "type": "shipments",
      "attributes": {
        "shipment_tracking_number": "33PKP0004327",
        "shipment_carrier": "Australia Post",
        "shipment_tracking_link": "https://auspost.com.au/mypost/track/#/details/33PKP0004327",
        "note": "Please handle with care",
        "dispatched_at": "2018-07-03T00:00:00.000+10:00"
      }
    }
  ]
}

Sending an invoice

This endpoint marks “Buy Online” invoices as sent out to the customer. It can take additional attributes such as postage information.

Request

PUT /api/v2/client/invoices/1/sent

Example

  data: {
    type: "invoices",
    attributes: {
      postage_tracking: "33PKP0004327",
      postage_carrier: "Australia Post",
      note: "Please handle with care"
    }
  }

Response

Status: 200 OK

{
  "links": {
    "self": "https://bikeexchange.com.au/api/v2/client/invoices/1"
  },
  "data": {
    "id": 1,
    "type": "invoices",
    "attributes": {
      "postage": "10.0",
      "paid_at": "2022-11-15T15:10:35+11:00",
      "status": "sent",
      "delivery_type": "click_and_collect",
      "ready_at": null,
      "collected_at": null,
      "subtotal": "110.0",
      "discount": "10",
      "total": "100",
      "tax_total": "0.0",
      "created_at": "2022-11-15T15:10:35+11:00",
      "tax_inclusive": true,
      "message_to_seller": "",
      "expected_delivery_date": "2022-11-19",
      "expected_delivery_slot": "Morning",
      "seller_id": 2
    },
    "relationships": {
      "line_items": {
        "data": [
          {
            "type": "line_items",
            "id": 1
          }
        ]
      },
      "shipments": {
        "data": [
          {
            "type": "shipments",
            "id": 1
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": 1,
      "type": "line_items",
      "attributes": {
        "price": "100.0",
        "status": "allocated",
        "subtotal": "100.",
        "tax_total": "0.0",
        "original_tax_rate": null,
        "total": "100.0",
        "quantity": 1,
        "taxon_name": "Hybrid Bikes",
        "brand_name": "Giant",
        "advert_name": "Giant Cypress DX",
        "advert_external_id": "ABC123",
        "variant_name": "Navy Blue / Medium",
        "variant_sku": null,
        "variant_barcode": "08717611735314",
        "variant_external_id": "DEF123"
      }
    },
    {
      "id": 1,
      "type": "shipments",
      "attributes": {
        "shipment_tracking_number": "33PKP0004327",
        "shipment_carrier": "Australia Post",
        "shipment_tracking_link": "https://auspost.com.au/mypost/track/#/details/33PKP0004327",
        "note": "Please handle with care",
        "dispatched_at": "2018-07-03T00:00:00.000+10:00"
      }
    }
  ]
}

Error Response

Status: 422 Unprocessable Entity

{
  "errors": [
      "Invoice must be paid or partially sent before we can mark it as sent."
  ]
}

Readying an invoice

This endpoint marks “Click and Collect” invoices as ready for collection.

Request

PUT /api/v2/client/invoices/1/ready

Response

Status: 200 OK

{
  "links": {
    "self": "https://bikeexchange.com.au/api/v2/client/invoices/1"
  },
  "data": {
    "id": 1,
    "type": "invoices",
    "attributes": {
      "postage": "10.0",
      "paid_at": "2022-11-15T15:10:35+11:00",
      "status": "ready",
      "delivery_type": "click_and_collect",
      "ready_at": "2022-11-17T15:10:35+11:00",
      "collected_at": null,
      "subtotal": "110.0",
      "discount": "10",
      "total": "100",
      "tax_total": "0.0",
      "created_at": "2022-11-15T15:10:35+11:00",
      "tax_inclusive": true,
      "message_to_seller": "",
      "expected_delivery_date": "2022-11-19",
      "expected_delivery_slot": "Morning",
      "seller_id": 2
    },
    "relationships": {
      "line_items": {
        "data": [
          {
            "type": "line_items",
            "id": 1
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": 1,
      "type": "line_items",
      "attributes": {
        "price": "100.0",
        "status": "allocated",
        "subtotal": "100.",
        "tax_total": "0.0",
        "original_tax_rate": null,
        "total": "100.0",
        "quantity": 1,
        "taxon_name": "Hybrid Bikes",
        "brand_name": "Giant",
        "advert_name": "Giant Cypress DX",
        "advert_external_id": "ABC123",
        "variant_name": "Navy Blue / Medium",
        "variant_sku": null,
        "variant_barcode": "08717611735314",
        "variant_external_id": "DEF123"
      }
    }
  ]
}

Marking an invoice as collected

This endpoint marks “Click and Collect” invoices as collected.

Request

PUT /api/v2/client/invoices/1/collected

Response

Status: 200 OK

{
  "links": {
    "self": "https://bikeexchange.com.au/api/v2/client/invoices/1"
  },
  "data": {
    "id": 1,
    "type": "invoices",
    "attributes": {
      "postage": "10.0",
      "paid_at": "2022-11-15T15:10:35+11:00",
      "status": "collected",
      "delivery_type": "click_and_collect",
      "ready_at": "2022-11-15T15:10:35+11:00",
      "collected_at": "2022-11-17T15:10:35+11:00",
      "subtotal": "110.0",
      "discount": "10",
      "total": "100",
      "tax_total": "0.0",
      "created_at": "2022-11-15T15:10:35+11:00",
      "tax_inclusive": true,
      "message_to_seller": "",
      "expected_delivery_date": "2022-11-19",
      "expected_delivery_slot": "Morning",
      "seller_id": 2
    },
    "relationships": {
      "line_items": {
        "data": [
          {
            "type": "line_items",
            "id": 1
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": 1,
      "type": "line_items",
      "attributes": {
        "price": "100.0",
        "status": "allocated",
        "subtotal": "100.",
        "tax_total": "0.0",
        "original_tax_rate": null,
        "total": "100.0",
        "quantity": 1,
        "taxon_name": "Hybrid Bikes",
        "brand_name": "Giant",
        "advert_name": "Giant Cypress DX",
        "advert_external_id": "ABC123",
        "variant_name": "Navy Blue / Medium",
        "variant_sku": null,
        "variant_barcode": "08717611735314",
        "variant_external_id": "DEF123"
      }
    }
  ]
}

🧨 Deprecations

10/05/2021: The refunded status is no longer valid.
17/10/2019: The postage_tracking and postage_carrier fields in the body of invoice data can now return comma delimited values if there was more than one shipment as part of an invoice.
10/07/2016: The ’tax_total’ field in the body of line item data is deprecated, as we are now calculating tax at an invoice level only. This field will continue to be provided, but its value will always be zero. Please refer to the tax_total for the invoice, which is unchanged.