Skip to content

Order Resource

Introduction

An order in the Open Publishing ecosystem is the data representation of an invoice. Invoices may have draft status - e.g. through an unfinished shopping cart or a draft/offer sent to a customer.

Example URL

https://api.openpublishing.com/resource/v3/orders/[ID]

Allowed methods: GET, PUT.

For creating an order POST an object to https://api.openpublishing.com/resource/v3/orders.

Search Filters

List orders:

https://api.openpublishing.com/resource/v3/orders

Filter by external identifiers:

https://api.openpublishing.com/resource/v3/orders?external_identifier_type=klopotek&external_identifier_value=503107

external_identifier_type / external_identifier_value : Search for orders with an external identifier set. The external identifier type is the category of the orders, e.g. "SAP" whereas the value is the id itself. If only external_identifier_type is specified, all orders with the external identifier type set are returned. If you search for only external_identifier_value - the system will return all identifiers with the value, where the type is not set.

Fields

Status

invoiced indicates if the order is open (false) or closed (true).

Invoice Number

invoice_number is the invoice number of the order or null if not set. The invoice number is set as consecutive by the backend if an order is closed. It is a read only field.

Invoice Date

invoice_date is the invoice date. It is set to today if not specified.

External Identifiers

external_identifiers: List of external/foreign identifiers, e.g. the id of the reference number within SAP. The listed objects are dicts with the values type for the type of the identifier and value for the identifier itself.

Invoice address

The invoice address subobject contains all information describing the invoice address of the order. The fields within the object are:

  • first_name the first name of the recipient.
  • last_name the last name of the recipient.
  • street, zip, city, state the address of the recipient. country contains the 2 character iso code of the country of the recipient.
  • email and phone_number contain contact information of the recipient.

All fields may be a string or null.

Shipping address

The shipping address subobject contains all information describing the shipping address of the order. The fields within the object are:

  • first_name the first name of the recipient.
  • last_name the last name of the recipient.
  • street, zip, city, state the address of the recipient. country contains the 2 character iso code of the country of the recipient.
  • email and phone_number contain contact information of the recipient.

All fields may be a string or null.

Language

language contains the 3 character language code in which the invoice should be printed. If set to null the op will pick reasonable defaults.

Currency

currency contains the 3 character currency ISO code (ISO 4217) of the items in the order. If unset or set to null, EUR is used as the default.

Title

The title field contains the name/subject of the order. A typical value could be Bestellung.

Shopping Cart information

The shopping_cart contains information for the checkout process. cart_return_url specifies a URL to which a user is redirected after sucessfull checkout process.

Status callback url

status_callback_urls may contain a list of URLS which are triggered on any status change of the order (e.g. sucessful fulfillment or a bounced payment.)

Invoice URL

invoice_url (read only) contains URL to download the PDF invoice. If it is set to null, then the invoice has not (yet) been created.

Total

total contains a struct with the sum of all order items. Fields within the struct are gross/gross_currency for the gross amount, net/net_currency for the net amount and vat/vat_currency for the vat amount. If the field cant be calculated (e.g. if currencies of order draft diverge) The whole field is set to null.

Realm

realm is the Open Publishing terminology for tenant. It contains a dict with _id and name and screenname.

Labels

The labels field contains a list of strings internally used for marking and grouping orders. These labels may be used to control the internal workflow and are not exported to external partners.

Example JSON

{
   "_id": 1,
   "external_identifiers":
      [
         {
            "type": "sap",
            "value": "1234"
         }
      ],
   "invoice_address": {
      "additional_information": null,
      "city": null,
      "company": null,
      "country": null,
      "email": "paypal-test@grin.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone_number": null,
      "state": null,
      "street": null,
      "zip": null
   },
   "invoice_date": "2021-10-05",
   "invoice_number": "R184-13281",
   "invoiced": true,
   "language": "ger",
   "currency": "eur",
   "realm": {
      "_id": 23,
      "name": "testpublisher",
      "screenname": "Test Publisher"
   },
   "shipping_address": {
      "additional_information": "Rückgebäude",
      "city": "München",
      "company": "XYZ GmbH",
      "country": "DE",
      "first_name": "John",
      "last_name": "Doe",
      "phone_number": "1234567",
      "state": "Bavaria",
      "street": "Marktplatz 12",
      "zip": "81479"
   },
   "shopping_cart": {
      "cart_return_url": "https://some-server.com/login/order/success"
   },
   "status_callback_urls":
      [
      "https://some-server.com/url/123"
      ],
   "title": "Ihre Bestellung",
   "total": {
      "gross": 4760,
      "gross_currency": "CHF",
      "net": 4000,
      "net_currency": "CHF",
      "vat": 760,
      "vat_currency": "CHF"
   },
   "invoice_url": "https://api.openpublishing.com/rpc/account_pdf?type=invoice&account_id=1"
}