Beyond is a cloud-based platform that offers a flexible and performant feature set to satisfy the varying requirements of the ecommerce business. Add new functionality or integrations, or build awesome ecommerce applications using the Beyond REST API. Our modern microservice architecture allows you to quickly develop your ecommerce solution by offering you access to services such as checkout, orders, products, payments, and many more. Anyone who is curious about our platform can sign up for a Beyond shop. You’re then free to set up an online shop via the cockpit, which is the merchant’s administration of a Beyond online shop.

Use cases

You plan an integration with ePages? That’s great! Get in touch with us to clarify the details. Here are already some use cases we can think of:

Integrate a payment solution

If you have a payment solution in place and would like to integrate with an ecommerce solution, this is where to start. Check our payment app documentation and find out how to integrate with Beyond!

Terminology

Before we jump right in, let’s look at the key terms that will be used throughout this documentation.

Name Description

App

The application that would like to interact with the payment gateway, thus integrate with Beyond.

Customer

The visitor of the online shop that is about to purchase products.

JWT

JSON Web Token. According to RFC-7519 a compact, URL-safe means of representing claims to be transferred between two parties.

Merchant

The owner of the online shop that will use your app.

Payment approval page

The page where the customer approves or cancels the payment with your app.

Payment gateway

The Beyond interface to payment apps. Provides an API contract that can be implemented in form of an app in order to integrate a payment with Beyond.

Storefront

The user interface of the customer.

Our requirements

In order to integrate with Beyond, your payment app needs to

  • communicate with our payment gateway

  • communicate with your backend

  • do the data mapping of the single merchant accounts

  • be run and operated by you, as we currently do not offer to run apps developed by 3rd parties in our system

There are no further requirements regarding your infrastructure as we are not directly communicating with your backend. Your backend will only communicate with your app. Our payment gateway will then forward the requests from the app towards our microservices. During the development and the integration of your app, we will stay in close contact. This way, we can bring certain development steps of your app into our infrastructure and test it.

In order to enable Beyond to send requests, you will have to provide several URIs upon creation of your app:

URI Required? Description Can be templated?

statusUri

Yes

Endpoint for the app’s integration status. Takes the shopID as parameter to refer to an individual shop.

Yes

createPaymentUri

Yes

Endpoint for the creation of individual payments. Can optionally take a paymentID as parameter.

Yes

capturePaymentUri

Yes

Endpoint to capture the payment after creation and approval have been successful. Takes a paymentID as parameter to refer to an individual payment.

Yes

referralUri

No

Endpoint that generates a reference to the site where the merchant can connect their shop with their payment app account.

No

disconnectUri

No

Endpoint to unlink a payment app account from a shop (with the URI generated by the app’s referralUri endpoint). Takes the shopID as parameter to refer to an individual shop.

Yes

refundPaymentUri

No

Endpoint to process refunds. Takes a paymentID as parameter to refer to an individual payment.

Yes

Payment Methods

Your app can manage different payment methods in our system using payment method definitions. You can create such a payment method definition once in our system using a system token. Afterwards, payment methods for single shops can be easily created from the payment method definition with a shop token.

What does this mean for the connection between single payment methods and their respective payment method definition? Each payment method needs to have a payment method definition and both are strongly connected. So, if the payment method definition is retrieved with a shop token, the response contains a link to create a payment method. If a payment method already exists, the response will contain a link to delete that payment method. This also means that if you delete a payment method definition, all related payment methods will also be deleted.

Retrieve a system access token

The client_credentials flow is used to create a system access token. With this token, you are able to do API calls on system level.

In general, the POST request for the system access token is similar to the one for creating a JsonWebToken. The only difference is that you need to make the request to the system access token endpoint using https://system.beyondshop.cloud/api/oauth/token.

Retrieve a payment method definition

A GET request is used to retrieve a payment method definition on system level.

Required scopes

paym:m

Example request

$ curl 'https://system.beyondshop.cloud/api/payment-method-definitions/credit-card' -i -X GET \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_id

String

The name of a payment method definition.

name

String

The name of a payment method definition.

referralUriTemplate

String

The URI template for the endpoint that generates a reference to the site where the merchant can connect their shop with their payment app account.

statusUriTemplate

String

The URI template for the endpoint for the app’s integration status. Takes the shopID as parameter to refer to an individual shop.

disconnectUriTemplate

String

The URI template for the endpoint to unlink a payment app account from a shop. Takes the shopID as parameter to refer to an individual shop.

createPaymentUriTemplate

String

The URI template for the endpoint for the creation of individual payments. Can optionally take a paymentID as parameter.

capturePaymentUriTemplate

String

The URI template for the endpoint to capture the payment after creation and approval have been successful. Takes a paymentID as parameter to refer to an individual payment.

refundPaymentUriTemplate

String

The URI template for the endpoint to process refunds. Takes a paymentID as parameter to refer to an individual payment.

sandbox

Boolean

Indicates if the payment method is using a sandbox environment. Can be true or false.

workflow

String

Indicates the workflow of the payment method. Can be one of PAYMENT_ON_SELECTION, EMBEDDED_ON_SELECTION, PAYMENT_ON_BUY, or EMBEDDED_ON_BUY.

captureWorkflow

String

Indicates how and when to capture an authorized payment. Can be one of CAPTURE_ON_ORDER or CAPTURE_ON_DEMAND.

refund

String

Gives information about the refund capabilities of the payment method. Can be one of NO_REFUND, FULL_REFUND_ONLY, or PARTIAL_REFUND.

logos[].setName

String

The set name of the logo. The default is official.

logos[].variant

String

The variant of the logo. Can be one of TILE, DETAILS, LIST, or STOREFRONT, depending on the location of the logo.

logos[].uri

String

The URI of the logo.

officialName

Object

The name of the payment method that will be displayed to the merchant. Needs to be translated for each supported language.

officialDescription

Object

The description of the payment method that will be displayed to the merchant. Needs to be translated for each supported language.

defaultName

Object

The default name of the payment method that will be displayed to the customer. Can be edited by the merchant and needs to be translated for each supported language.

defaultDescription

Object

Optional default description of the payment method that will be displayed to the customer. Can be edited by the merchant and needs to be translated for each supported language.

_links

Object

See Hypermedia

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1395

{
  "_id" : "credit-card",
  "name" : "credit-card",
  "referralUriTemplate" : "https://example.com/merchants",
  "statusUriTemplate" : "https://example.com/merchants/{shopId}/status",
  "disconnectUriTemplate" : "https://example.com/merchants/{shopId}/disconnect",
  "createPaymentUriTemplate" : "https://example.com/payments",
  "capturePaymentUriTemplate" : "https://example.com/payments/{paymentId}/capture",
  "refundPaymentUriTemplate" : "https://example.com/payments/{paymentId}/refund",
  "sandbox" : true,
  "workflow" : "PAYMENT_ON_BUY",
  "captureWorkflow" : "CAPTURE_ON_ORDER",
  "refund" : "NO_REFUND",
  "logos" : [ {
    "setName" : "official",
    "variant" : "STOREFRONT",
    "uri" : "https://example.com/static/storefront.png"
  } ],
  "officialName" : {
    "de-DE" : "Ermögliche deinen Kunden, mit Kreditkarte zu bezahlen.",
    "en-US" : "Allow your customers to pay by credit card."
  },
  "officialDescription" : {
    "de-DE" : "Ermögliche deinen Kunden, mit Kreditkarte zu bezahlen.",
    "en-US" : "Allow your customers to pay by credit card."
  },
  "defaultDescription" : {
    "de-DE" : "Bezahlen Sie mit Kreditkarte.",
    "en-US" : "Pay by credit card."
  },
  "defaultName" : {
    "de-DE" : "Kreditkarte",
    "en-US" : "Credit card"
  },
  "_links" : {
    "self" : {
      "href" : "https://system.beyondshop.cloud/api/payment-method-definitions/credit-card"
    }
  }
}
Retrieve already existing payment methods

A GET request is used to retrieve a payment method definition on shop level. If a payment method of this payment method definition already exists, the response includes a link to delete it. If not, the response includes a link to create it.

Required scopes

paym:m

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/payment-method-definitions/testPMD' -i -X GET \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_id

String

The name of a payment method definition.

name

String

The name of a payment method definition.

referralUriTemplate

String

The URI template for the endpoint that generates a reference to the site where the merchant can connect their shop with their payment app account.

statusUriTemplate

String

The URI template for the endpoint for the app’s integration status. Takes the shopID as parameter to refer to an individual shop.

disconnectUriTemplate

String

The URI template for the endpoint to unlink a payment app account from a shop. Takes the shopID as parameter to refer to an individual shop.

createPaymentUriTemplate

String

The URI template for the endpoint for the creation of individual payments. Can optionally take a paymentID as parameter.

capturePaymentUriTemplate

String

The URI template for the endpoint to capture the payment after creation and approval have been successful. Takes a paymentID as parameter to refer to an individual payment.

refundPaymentUriTemplate

String

The URI template for the endpoint to process refunds. Takes a paymentID as parameter to refer to an individual payment.

sandbox

Boolean

Indicates if the payment method is using a sandbox environment. Can be true or false.

workflow

String

Indicates the workflow of the payment method. Can be one of PAYMENT_ON_SELECTION, EMBEDDED_ON_SELECTION, PAYMENT_ON_BUY, or EMBEDDED_ON_BUY.

captureWorkflow

String

Indicates how and when to capture an authorized payment. Can be one of CAPTURE_ON_ORDER or CAPTURE_ON_DEMAND.

refund

String

Gives information about the refund capabilities of the payment method. Can be one of NO_REFUND, FULL_REFUND_ONLY, or PARTIAL_REFUND.

logos[].setName

String

The set name of the logo. The default is official.

logos[].variant

String

The variant of the logo. Can be one of TILE, DETAILS, LIST, or STOREFRONT, depending on the location of the logo.

logos[].uri

String

The URI of the logo.

officialName

Object

The name of the payment method that will be displayed to the merchant. Needs to be translated for each supported language.

officialDescription

Object

The description of the payment method that will be displayed to the merchant. Needs to be translated for each supported language.

defaultName

Object

The default name of the payment method that will be displayed to the customer. Can be edited by the merchant and needs to be translated for each supported language.

defaultDescription

Object

Optional default description of the payment method that will be displayed to the customer. Can be edited by the merchant and needs to be translated for each supported language.

_links

Object

See Hypermedia

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1516

{
  "_id" : "testPMD",
  "name" : "testPMD",
  "referralUriTemplate" : "https://example.com/merchants",
  "statusUriTemplate" : "https://example.com/merchants/{shopId}/status",
  "disconnectUriTemplate" : "https://example.com/merchants/{shopId}/disconnect",
  "createPaymentUriTemplate" : "https://example.com/payments",
  "capturePaymentUriTemplate" : "https://example.com/payments/{paymentId}/capture",
  "refundPaymentUriTemplate" : "https://example.com/payments/{paymentId}/refund",
  "sandbox" : true,
  "workflow" : "PAYMENT_ON_BUY",
  "captureWorkflow" : "CAPTURE_ON_ORDER",
  "refund" : "NO_REFUND",
  "logos" : [ {
    "setName" : "official",
    "variant" : "STOREFRONT",
    "uri" : "https://example.com/static/storefront.png"
  } ],
  "officialName" : {
    "de-DE" : "Ermögliche deinen Kunden, mit Kreditkarte zu bezahlen.",
    "en-US" : "Allow your customers to pay by credit card."
  },
  "officialDescription" : {
    "de-DE" : "Ermögliche deinen Kunden, mit Kreditkarte zu bezahlen.",
    "en-US" : "Allow your customers to pay by credit card."
  },
  "defaultDescription" : {
    "de-DE" : "Bezahlen Sie mit Kreditkarte.",
    "en-US" : "Pay by credit card."
  },
  "defaultName" : {
    "de-DE" : "Kreditkarte",
    "en-US" : "Credit card"
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-method-definitions/testPMD"
    },
    "create-payment-method" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-method-definitions/testPMD/payment-method"
    }
  }
}
List payment method definitions

A GET request is used to list all payment method definitions.

Required scopes

paym:m

Example request

$ curl 'https://system.beyondshop.cloud/api/payment-method-definitions' -i -X GET \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_embedded.payment-method-definitions[]._id

String

The name of a payment method definition.

_embedded.payment-method-definitions[].name

String

The name of a payment method definition.

_embedded.payment-method-definitions[].referralUriTemplate

String

The URI template for the endpoint that generates a reference to the site where the merchant can connect their shop with their payment app account.

_embedded.payment-method-definitions[].statusUriTemplate

String

The URI template for the endpoint for the app’s integration status. Takes the shopID as parameter to refer to an individual shop.

_embedded.payment-method-definitions[].disconnectUriTemplate

String

The URI template for the endpoint to unlink a payment app account from a shop. Takes the shopID as parameter to refer to an individual shop.

_embedded.payment-method-definitions[].createPaymentUriTemplate

String

The URI template for the endpoint for the creation of individual payments. Can optionally take a paymentID as parameter.

_embedded.payment-method-definitions[].capturePaymentUriTemplate

String

The URI template for the endpoint to capture the payment after creation and approval have been successful. Takes a paymentID as parameter to refer to an individual payment.

_embedded.payment-method-definitions[].refundPaymentUriTemplate

String

The URI template for the endpoint to process refunds. Takes a paymentID as parameter to refer to an individual payment.

_embedded.payment-method-definitions[].sandbox

Boolean

Indicates if the payment method is using a sandbox environment. Can be true or false.

_embedded.payment-method-definitions[].workflow

String

Indicates the workflow of the payment method. Can be one of PAYMENT_ON_SELECTION, EMBEDDED_ON_SELECTION, PAYMENT_ON_BUY, or EMBEDDED_ON_BUY.

_embedded.payment-method-definitions[].captureWorkflow

String

Indicates how and when to capture an authorized payment. Can be one of CAPTURE_ON_ORDER or CAPTURE_ON_DEMAND.

_embedded.payment-method-definitions[].refund

String

Gives information about the refund capabilities of the payment method. Can be one of NO_REFUND, FULL_REFUND_ONLY, or PARTIAL_REFUND.

_embedded.payment-method-definitions[].logos[].setName

String

The set name of the logo. The default is official.

_embedded.payment-method-definitions[].logos[].variant

String

The variant of the logo. Can be one of TILE, DETAILS, LIST, or STOREFRONT, depending on the location of the logo.

_embedded.payment-method-definitions[].logos[].uri

String

The URI of the logo.

_embedded.payment-method-definitions[]._links

Object

See Hypermedia

_embedded.payment-method-definitions[].officialName

Object

The name of the payment method that will be displayed to the merchant. Needs to be translated for each supported language.

_embedded.payment-method-definitions[].officialDescription

Object

The description of the payment method that will be displayed to the merchant. Needs to be translated for each supported language.

_embedded.payment-method-definitions[].defaultName

Object

The default name of the payment method that will be displayed to the customer. Can be edited by the merchant and needs to be translated for each supported language.

_embedded.payment-method-definitions[].defaultDescription

Object

Optional default description of the payment method that will be displayed to the customer. Can be edited by the merchant and needs to be translated for each supported language.

_links

Object

See Hypermedia

page

Object

See Pagination

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1838

{
  "_embedded" : {
    "payment-method-definitions" : [ {
      "_id" : "credit-card",
      "name" : "credit-card",
      "referralUriTemplate" : "https://example.com/merchants",
      "statusUriTemplate" : "https://example.com/merchants/{shopId}/status",
      "disconnectUriTemplate" : "https://example.com/merchants/{shopId}/disconnect",
      "createPaymentUriTemplate" : "https://example.com/payments",
      "capturePaymentUriTemplate" : "https://example.com/payments/{paymentId}/capture",
      "refundPaymentUriTemplate" : "https://example.com/payments/{paymentId}/refund",
      "sandbox" : true,
      "workflow" : "PAYMENT_ON_BUY",
      "captureWorkflow" : "CAPTURE_ON_ORDER",
      "refund" : "NO_REFUND",
      "logos" : [ {
        "setName" : "official",
        "variant" : "STOREFRONT",
        "uri" : "https://example.com/static/storefront.png"
      } ],
      "officialName" : {
        "de-DE" : "Ermögliche deinen Kunden, mit Kreditkarte zu bezahlen.",
        "en-US" : "Allow your customers to pay by credit card."
      },
      "officialDescription" : {
        "de-DE" : "Ermögliche deinen Kunden, mit Kreditkarte zu bezahlen.",
        "en-US" : "Allow your customers to pay by credit card."
      },
      "defaultDescription" : {
        "de-DE" : "Bezahlen Sie mit Kreditkarte.",
        "en-US" : "Pay by credit card."
      },
      "defaultName" : {
        "de-DE" : "Kreditkarte",
        "en-US" : "Credit card"
      },
      "_links" : {
        "self" : {
          "href" : "https://system.beyondshop.cloud/api/payment-method-definitions/credit-card"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://system.beyondshop.cloud/api/payment-method-definitions?page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}
Create a payment method definition

A POST request is used to create a payment method definition.

Required scopes

paym:m

Request body properties

Path Type Description Constraints

name

String

The name of a payment method definition.

Must not be null. Size must be between 0 and 50 inclusive

referralUriTemplate

String

The URI template for the endpoint that generates a reference to the site where the merchant can connect their shop with their payment app account.

Size must be between 0 and 1024 inclusive

statusUriTemplate

String

The URI template for the endpoint for the app’s integration status. Takes the shopID as parameter to refer to an individual shop.

Must not be null. Size must be between 0 and 1024 inclusive

disconnectUriTemplate

String

The URI template for the endpoint to unlink a payment app account from a shop. Takes the shopID as parameter to refer to an individual shop.

Size must be between 0 and 1024 inclusive

createPaymentUriTemplate

String

The URI template for the endpoint for the creation of individual payments. Can optionally take a paymentID as parameter.

Size must be between 0 and 1024 inclusive

capturePaymentUriTemplate

String

The URI template for the endpoint to capture the payment after creation and approval have been successful. Takes a paymentID as parameter to refer to an individual payment.

Must not be null. Size must be between 0 and 1024 inclusive

refundPaymentUriTemplate

String

The URI template for the endpoint to process refunds. Takes a paymentID as parameter to refer to an individual payment.

Size must be between 0 and 1024 inclusive

workflow

String

Indicates the workflow of the payment method. Can be one of PAYMENT_ON_SELECTION, EMBEDDED_ON_SELECTION, PAYMENT_ON_BUY, or EMBEDDED_ON_BUY.

Must not be null

captureWorkflow

String

Indicates how and when to capture an authorized payment. Can be one of CAPTURE_ON_ORDER or CAPTURE_ON_DEMAND.

Must not be null

refund

String

Gives information about the refund capabilities of the payment method. Can be one of NO_REFUND, FULL_REFUND_ONLY, or PARTIAL_REFUND.

Must not be null

logos[].setName

String

The set name of the logo. The default is official.

logos[].variant

String

The variant of the logo. Can be one of TILE, DETAILS, LIST, or STOREFRONT, depending on the location of the logo.

logos[].uri

String

The URI of the logo.

officialName

Object

The name of the payment method that will be displayed to the merchant. Needs to be translated for each supported language.

officialDescription

Object

The description of the payment method that will be displayed to the merchant. Needs to be translated for each supported language.

defaultName

Object

The default name of the payment method that will be displayed to the customer. Can be edited by the merchant and needs to be translated for each supported language.

defaultDescription

Object

Optional default description of the payment method that will be displayed to the customer. Can be edited by the merchant and needs to be translated for each supported language.

sandbox

String

Indicates if the payment method is using a sandbox environment. Can be true or false.

Must not be null

Example request

$ curl 'https://system.beyondshop.cloud/api/payment-method-definitions' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{
  "name": "credit-card",
  "referralUriTemplate": "https://example.com/merchants",
  "statusUriTemplate": "https://example.com/merchants/{shopId}/status",
  "disconnectUriTemplate": "https://example.com/merchants/{shopId}/disconnect",
  "createPaymentUriTemplate": "https://example.com/payments",
  "capturePaymentUriTemplate": "https://example.com/payments/{paymentId}/capture",
  "refundPaymentUriTemplate": "https://example.com/payments/{paymentId}/refund",
"sandbox": "true",
  "workflow": "PAYMENT_ON_BUY",
  "captureWorkflow": "CAPTURE_ON_ORDER",
  "refund": "NO_REFUND",
  "logos": [{
    "setName" : "official",
    "variant" : "STOREFRONT",
    "uri" : "https://example.com/static/storefront.png"
  }],
"officialName": {"de-DE" : "Ermögliche deinen Kunden, mit Kreditkarte zu bezahlen.",
"en-US" : "Allow your customers to pay by credit card."
},
  "officialDescription": {
    "de-DE" : "Ermögliche deinen Kunden, mit Kreditkarte zu bezahlen.",
    "en-US" : "Allow your customers to pay by credit card."
  },
  "defaultName": {
    "de-DE" : "Kreditkarte",
    "en-US" : "Credit card"
  },
  "defaultDescription": {"de-DE" : "Bezahlen Sie mit Kreditkarte.","en-US" : "Pay by credit card."}}'

Response body properties

Path Type Description

_id

String

The name of a payment method definition.

name

String

The name of a payment method definition.

referralUriTemplate

String

The URI template for the endpoint that generates a reference to the site where the merchant can connect their shop with their payment app account.

statusUriTemplate

String

The URI template for the endpoint for the app’s integration status. Takes the shopID as parameter to refer to an individual shop.

disconnectUriTemplate

String

The URI template for the endpoint to unlink a payment app account from a shop. Takes the shopID as parameter to refer to an individual shop.

createPaymentUriTemplate

String

The URI template for the endpoint for the creation of individual payments. Can optionally take a paymentID as parameter.

capturePaymentUriTemplate

String

The URI template for the endpoint to capture the payment after creation and approval have been successful. Takes a paymentID as parameter to refer to an individual payment.

refundPaymentUriTemplate

String

The URI template for the endpoint to process refunds. Takes a paymentID as parameter to refer to an individual payment.

sandbox

Boolean

Indicates if the payment method is using a sandbox environment. Can be true or false.

workflow

String

Indicates the workflow of the payment method. Can be one of PAYMENT_ON_SELECTION, EMBEDDED_ON_SELECTION, PAYMENT_ON_BUY, or EMBEDDED_ON_BUY.

captureWorkflow

String

Indicates how and when to capture an authorized payment. Can be one of CAPTURE_ON_ORDER or CAPTURE_ON_DEMAND.

refund

String

Gives information about the refund capabilities of the payment method. Can be one of NO_REFUND, FULL_REFUND_ONLY, or PARTIAL_REFUND.

logos[].setName

String

The set name of the logo. The default is official.

logos[].variant

String

The variant of the logo. Can be one of TILE, DETAILS, LIST, or STOREFRONT, depending on the location of the logo.

logos[].uri

String

The URI of the logo.

officialName

Object

The name of the payment method that will be displayed to the merchant. Needs to be translated for each supported language.

officialDescription

Object

The description of the payment method that will be displayed to the merchant. Needs to be translated for each supported language.

defaultName

Object

The default name of the payment method that will be displayed to the customer. Can be edited by the merchant and needs to be translated for each supported language.

defaultDescription

Object

Optional default description of the payment method that will be displayed to the customer. Can be edited by the merchant and needs to be translated for each supported language.

_links

Object

See Hypermedia

Example response

HTTP/1.1 201 Created
Location: https://system.beyondshop.cloud/api/paymentMethodDefinitions/credit-card
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1395

{
  "_id" : "credit-card",
  "name" : "credit-card",
  "referralUriTemplate" : "https://example.com/merchants",
  "statusUriTemplate" : "https://example.com/merchants/{shopId}/status",
  "disconnectUriTemplate" : "https://example.com/merchants/{shopId}/disconnect",
  "createPaymentUriTemplate" : "https://example.com/payments",
  "capturePaymentUriTemplate" : "https://example.com/payments/{paymentId}/capture",
  "refundPaymentUriTemplate" : "https://example.com/payments/{paymentId}/refund",
  "sandbox" : true,
  "workflow" : "PAYMENT_ON_BUY",
  "captureWorkflow" : "CAPTURE_ON_ORDER",
  "refund" : "NO_REFUND",
  "logos" : [ {
    "setName" : "official",
    "variant" : "STOREFRONT",
    "uri" : "https://example.com/static/storefront.png"
  } ],
  "officialName" : {
    "de-DE" : "Ermögliche deinen Kunden, mit Kreditkarte zu bezahlen.",
    "en-US" : "Allow your customers to pay by credit card."
  },
  "officialDescription" : {
    "de-DE" : "Ermögliche deinen Kunden, mit Kreditkarte zu bezahlen.",
    "en-US" : "Allow your customers to pay by credit card."
  },
  "defaultDescription" : {
    "de-DE" : "Bezahlen Sie mit Kreditkarte.",
    "en-US" : "Pay by credit card."
  },
  "defaultName" : {
    "de-DE" : "Kreditkarte",
    "en-US" : "Credit card"
  },
  "_links" : {
    "self" : {
      "href" : "https://system.beyondshop.cloud/api/payment-method-definitions/credit-card"
    }
  }
}
Update a payment method definition

A PUT request is used to update a payment method definition.

Required scopes

paym:m

Request body properties

Path Type Description Constraints

name

String

The name of a payment method definition.

Must not be null. Size must be between 0 and 50 inclusive

referralUriTemplate

String

The URI template for the endpoint that generates a reference to the site where the merchant can connect their shop with their payment app account.

Size must be between 0 and 1024 inclusive

statusUriTemplate

String

The URI template for the endpoint for the app’s integration status. Takes the shopID as parameter to refer to an individual shop.

Must not be null. Size must be between 0 and 1024 inclusive

disconnectUriTemplate

String

The URI template for the endpoint to unlink a payment app account from a shop. Takes the shopID as parameter to refer to an individual shop.

Size must be between 0 and 1024 inclusive

createPaymentUriTemplate

String

The URI template for the endpoint for the creation of individual payments. Can optionally take a paymentID as parameter.

Size must be between 0 and 1024 inclusive

capturePaymentUriTemplate

String

The URI template for the endpoint to capture the payment after creation and approval have been successful. Takes a paymentID as parameter to refer to an individual payment.

Must not be null. Size must be between 0 and 1024 inclusive

refundPaymentUriTemplate

String

The URI template for the endpoint to process refunds. Takes a paymentID as parameter to refer to an individual payment.

Size must be between 0 and 1024 inclusive

workflow

String

Indicates the workflow of the payment method. Can be one of PAYMENT_ON_SELECTION, EMBEDDED_ON_SELECTION, PAYMENT_ON_BUY, or EMBEDDED_ON_BUY.

Must not be null

captureWorkflow

String

Indicates how and when to capture an authorized payment. Can be one of CAPTURE_ON_ORDER or CAPTURE_ON_DEMAND.

Must not be null

refund

String

Gives information about the refund capabilities of the payment method. Can be one of NO_REFUND, FULL_REFUND_ONLY, or PARTIAL_REFUND.

Must not be null

logos[].setName

String

The set name of the logo. The default is official.

logos[].variant

String

The variant of the logo. Can be one of TILE, DETAILS, LIST, or STOREFRONT, depending on the location of the logo.

logos[].uri

String

The URI of the logo.

officialName

Object

The name of the payment method that will be displayed to the merchant. Needs to be translated for each supported language.

officialDescription

Object

The description of the payment method that will be displayed to the merchant. Needs to be translated for each supported language.

defaultName

Object

The default name of the payment method that will be displayed to the customer. Can be edited by the merchant and needs to be translated for each supported language.

defaultDescription

Object

Optional default description of the payment method that will be displayed to the customer. Can be edited by the merchant and needs to be translated for each supported language.

Example request

$ curl 'https://system.beyondshop.cloud/api/payment-method-definitions/credit-card' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{
  "name": "credit-card-updated",
  "referralUriTemplate": "https://example.com/merchants",
  "statusUriTemplate": "https://example.com/merchants/{shopId}/status",
  "disconnectUriTemplate": "https://example.com/merchants/{shopId}/disconnect",
  "createPaymentUriTemplate": "https://example.com/payments",
  "capturePaymentUriTemplate": "https://example.com/payments/{paymentId}/capture",
  "refundPaymentUriTemplate": "https://example.com/payments/{paymentId}/refund",
  "workflow": "PAYMENT_ON_SELECTION",
  "captureWorkflow": "CAPTURE_ON_ORDER",
  "refund": "NO_REFUND",
  "logos": [{
    "setName" : "official",
    "variant" : "STOREFRONT",
    "uri" : "https://example.com/static/storefront.png"
  }],
"officialName": {"de-DE" : "Ermögliche deinen Kunden, mit Kreditkarte zu bezahlen.",
"en-US" : "Allow your customers to pay by credit card."
},
  "officialDescription": {
    "de-DE" : "Ermögliche deinen Kunden, mit Kreditkarte zu bezahlen.",
    "en-US" : "Allow your customers to pay by credit card."
  },
  "defaultName": {
    "de-DE" : "Kreditkarte",
    "en-US" : "Credit card"
  },
  "defaultDescription": {"de-DE" : "Bezahlen Sie mit Kreditkarte.","en-US" : "Pay by credit card."}}'

Response body properties

Path Type Description

_id

String

The name of a payment method definition.

name

String

The name of a payment method definition.

referralUriTemplate

String

The URI template for the endpoint that generates a reference to the site where the merchant can connect their shop with their payment app account.

statusUriTemplate

String

The URI template for the endpoint for the app’s integration status. Takes the shopID as parameter to refer to an individual shop.

disconnectUriTemplate

String

The URI template for the endpoint to unlink a payment app account from a shop. Takes the shopID as parameter to refer to an individual shop.

createPaymentUriTemplate

String

The URI template for the endpoint for the creation of individual payments. Can optionally take a paymentID as parameter.

capturePaymentUriTemplate

String

The URI template for the endpoint to capture the payment after creation and approval have been successful. Takes a paymentID as parameter to refer to an individual payment.

refundPaymentUriTemplate

String

The URI template for the endpoint to process refunds. Takes a paymentID as parameter to refer to an individual payment.

sandbox

Boolean

Indicates if the payment method is using a sandbox environment. Can be true or false.

workflow

String

Indicates the workflow of the payment method. Can be one of PAYMENT_ON_SELECTION, EMBEDDED_ON_SELECTION, PAYMENT_ON_BUY, or EMBEDDED_ON_BUY.

captureWorkflow

String

Indicates how and when to capture an authorized payment. Can be one of CAPTURE_ON_ORDER or CAPTURE_ON_DEMAND.

refund

String

Gives information about the refund capabilities of the payment method. Can be one of NO_REFUND, FULL_REFUND_ONLY, or PARTIAL_REFUND.

logos[].setName

String

The set name of the logo. The default is official.

logos[].variant

String

The variant of the logo. Can be one of TILE, DETAILS, LIST, or STOREFRONT, depending on the location of the logo.

logos[].uri

String

The URI of the logo.

officialName

Object

The name of the payment method that will be displayed to the merchant. Needs to be translated for each supported language.

officialDescription

Object

The description of the payment method that will be displayed to the merchant. Needs to be translated for each supported language.

defaultName

Object

The default name of the payment method that will be displayed to the customer. Can be edited by the merchant and needs to be translated for each supported language.

defaultDescription

Object

Optional default description of the payment method that will be displayed to the customer. Can be edited by the merchant and needs to be translated for each supported language.

_links

Object

See Hypermedia

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1401

{
  "_id" : "credit-card",
  "name" : "credit-card",
  "referralUriTemplate" : "https://example.com/merchants",
  "statusUriTemplate" : "https://example.com/merchants/{shopId}/status",
  "disconnectUriTemplate" : "https://example.com/merchants/{shopId}/disconnect",
  "createPaymentUriTemplate" : "https://example.com/payments",
  "capturePaymentUriTemplate" : "https://example.com/payments/{paymentId}/capture",
  "refundPaymentUriTemplate" : "https://example.com/payments/{paymentId}/refund",
  "sandbox" : true,
  "workflow" : "PAYMENT_ON_SELECTION",
  "captureWorkflow" : "CAPTURE_ON_ORDER",
  "refund" : "NO_REFUND",
  "logos" : [ {
    "setName" : "official",
    "variant" : "STOREFRONT",
    "uri" : "https://example.com/static/storefront.png"
  } ],
  "officialName" : {
    "de-DE" : "Ermögliche deinen Kunden, mit Kreditkarte zu bezahlen.",
    "en-US" : "Allow your customers to pay by credit card."
  },
  "officialDescription" : {
    "de-DE" : "Ermögliche deinen Kunden, mit Kreditkarte zu bezahlen.",
    "en-US" : "Allow your customers to pay by credit card."
  },
  "defaultDescription" : {
    "de-DE" : "Bezahlen Sie mit Kreditkarte.",
    "en-US" : "Pay by credit card."
  },
  "defaultName" : {
    "de-DE" : "Kreditkarte",
    "en-US" : "Credit card"
  },
  "_links" : {
    "self" : {
      "href" : "https://system.beyondshop.cloud/api/payment-method-definitions/credit-card"
    }
  }
}
Delete a payment method definition

A DELETE request is used to delete a payment method definition.

Required scopes

paym:m

Example request

$ curl 'https://system.beyondshop.cloud/api/payment-method-definitions/credit-card' -i -X DELETE \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 204 No Content
Create a payment method

A POST request is used to create a payment method from a payment method definition.

Required scopes

paym:m

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/payment-method-definitions/testPMD/payment-method' -i -X POST \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 200 OK
Delete a payment method

A DELETE request is used to delete a payment method from a payment method definition.

Required scopes

paym:m

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/payment-method-definitions/testPMD/payment-method' -i -X DELETE \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 200 OK

Authorization

Your app cannot access merchant data without authorizing first. For this authorization, we use the OAuth 2.0 flow for all kinds of apps in our system. You’ll find all relevant information on this in the App development section.

Apart from that, payment apps require additonal steps to ensure a flawless communication between merchant, Beyond API, and your app:

Retrieve a shopId

The app needs to store the shopId. It can be retrieved with the following GET request:

Required scopes

paym:m

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/shop-id' -i -X GET \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 55

{
  "shopId" : "187d8927-f606-4df1-a959-740b37ad8df3"
}
Create a signer

Every request in the communication between the payment gateway and the app should be signed. A signer is not mandatory, but highly recommended. It serves two purposes:

  • Ensures that the sender of the request is your trusted partner.

  • Ensures that the request was not modified during transaction.

You can create a signer by using a POST request.

Connection to the merchant account

The merchant needs to connect their shop with their payment app account. That means, that they authorize your app to communicate with your backend on their behalf. In general, the merchant registers credentials in the app that allow the app to create and update payments on their behalf. This registration can be implemented in various ways. We currently only support a referral process for the registration. In such a referral process, the app can use shop data, such as customer address, or email address. Additionally, the app’s referralUri generates a reference to redirect the merchant to a page where they can perform a self-signup.

If you would like to use a different process, get in touch with us. Otherwise, here’s what you need to do for the referral process:

Generate referral URI

In order to initiate a referral process, the app needs to generate the referralUri with a POST request.

Required scopes

pymt:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/payment-signup/referrals/credit-card' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{ "referralReturnUri": "https://cornershop.beyondshop.cloud/cockpit" }'

Response body properties

Path Type Description

referralUri

String

The endpoint that generates a reference to the site where the merchant can connect their shop with their payment app account.

_links

Object

See Hypermedia

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 238

{
  "referralUri" : "http://localhost/referral",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-signup/referrals/credit-card"
    },
    "referral" : {
      "href" : "http://localhost/referral"
    }
  }
}

The payment gateway will then provide details about the merchant, such as merchant address or email address, as a POST request to the payment app. This way, the related fields can already be pre-filled and the merchant can register more easily.

Request body properties

Path Type Description

shop

Object

A complete shop object. See shops resource for more information.

shopUri

String

The URI of the shop.

redirectUri

String

The URI to which the customer will be redirected after the referral process.

Example request

$ curl 'https://app.example.com/api/referrals' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -d '{
  "shop" : {
    "id" : "d2344dab-6a07-4783-87c8-2901ca9bd76c",
    "name" : "My little Cornershop",
    "address" : {
      "company" : null,
      "firstName" : "Beryl",
      "lastName" : "Mannar",
      "email" : "bm@example.com",
      "phone" : null,
      "fax" : null,
      "street" : "Malevo Drive",
      "street2" : null,
      "postalCode" : "WC1D 8DU",
      "city" : "Minessace",
      "country" : "GB",
      "state" : null
    },
    "defaultCurrency" : "EUR",
    "defaultLocale" : "en-GB"
  },
  "shopUri" : "https://cornershop.beyondshop.cloud",
  "redirectUri" : "https://cornershop.beyondshop.cloud/cockpit"
}'

Response body properties

Path Type Description

referralUri

String

The endpoint that generates a reference to the site where the merchant can connect their shop with their payment app account.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 58

{
  "referralUri" : "https://www.app.example.com/signup"
}
Retrieve status of merchant registration

The Beyond API makes a GET request to retrieve the current status of the merchant registration from the app.

Example request

$ curl 'https://app.example.com/api/merchant-account-status/663f114d-c674-4241-bdaf-b79a5133a50c' -i -X GET \
    -H 'Accept: application/hal+json'

Response body properties

Path Type Description

ready

Boolean

Indicates if the account is properly connected to the payment app.

details

Object

Gives information about the account that is connected to the payment app.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 85

{
  "ready" : true,
  "details" : {
    "primaryEmail" : "blackhole@epages.com"
  }
}

If the response is "ready":true, the referral process was successful and the merchant account is connected with the app.

Payment flow

You have several options to set up the payment workflow:

  • PAYMENT_ON_BUY
    The payment flow is triggered after the customer selected the button Buy now in the checkout. The payment itself is processed on the payment approval page of the payment provider.

  • EMBEDDED_ON_BUY
    The payment flow is triggered after the customer selected the button Buy now in the checkout. The payment itself is processed in an embedded iframe in the checkout.

  • PAYMENT_ON_SELECTION
    The payment flow is triggered after the customer selected the related payment method in the payment step of the checkout. The payment itself is processed on the payment approval page of the payment provider.

  • EMBEDDED_ON_SELECTION
    The payment flow is triggered after the customer selected the related payment method in the payment step of the checkout. The payment itself is processed in an embedded iframe in the checkout.

You can decide which option to choose for your payment solution. The general payment flow stays the same. The following diagram illustrates the possible status transitions within the payment flow:

paymentStatus

Each node in this graph is idempotent, meaning that trying to set a payment to a status it already has will not produce an error. Those paymentStatus values have the following meanings:

Status

Description

PENDING

The default status upon creation of a new payment waiting to be processed.

APPROVED

The customer has given their consent to proceed with the payment.

CANCELED

The processing of the payment has been terminated as a result of the customer’s decision.

CAPTURE_PENDING

The payment gateway has to wait for further notice to capture the payment. Functionally equivalent to APPROVED.

CAPTURED

The payment flow has been completed successfully.

FAILED

The payment could not be completed successfully due to an error.

Here’s an overview of the general payment flow:

PaymentFlowChart
Figure 1. Payment flow

The flow is divided into two main sections:

  • Creating the payment during the checkout (step 1 & 2 of Fig.2).

  • Capturing the payment when the order is created (step 3 of Fig.2).

Both of these sections and the related requests are further explained in the following:

1. Create a payment

The customer adds items to their cart, and starts with the checkout. During the checkout, a POST request is triggered from the Beyond API to the payment app to create the payment. It depends on the chosen workflow (PAYMENT_ON_SELECTION, EMBEDDED_ON_SELECTION, PAYMENT_ON_BUY, or EMBEDDED_ON_BUY) when this POST request will be triggered.

With the POST request the payment gateway will provide a paymentId and an errorUri as well as related cart and shop information. As a response to this request, your app should return an approvalUri for the PAYMENT_ON_SELECTION and PAYMENT_ON_BUY workflow or an embeddedApprovalUri for the EMBEDDED_ON_SELECTION and EMBEDDED_ON_BUY workflow. Optionally, you can also provide a paymentNote that will be rendered on the order documents.

For payments that do not need further redirects (e.g. payment in advance), the approvalUri and embeddedApprovalUri can be omitted, but at least the paymentNote should be provided. In this case, steps 2 and 3 can be ignored.

See below the related POST request:

Request body properties

Path Type Description

paymentId

String

The unique identifier of the payment.

shopId

String

The unique identifier of the shop.

shop.name

String

The name of the shop.

errorUri

String

The URI to which the customer will be redirected if an unexpected errors occurs during a redirect.

cart

Object

A complete cart object. See carts resource for more information.

Example request

$ curl 'https://app.example.com/api/payments' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -d '{
  "cart" : {
    "_id" : "96a0f6bd-ab2b-4dc2-9833-bbfe9dda2798",
    "lineItems" : [ {
      "productName" : "The comprehensive origami course",
      "productSku" : null,
      "quantity" : 0,
      "lineItemTax" : null,
      "lineItemPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 74.95
      },
      "singleItemPrice" : null
    }, {
      "productName" : "High Protein Power Bar (Pack of 5)",
      "productSku" : null,
      "quantity" : 0,
      "lineItemTax" : null,
      "lineItemPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 4.95
      },
      "singleItemPrice" : null
    } ],
    "billingAddress" : {
      "company" : null,
      "title" : null,
      "firstName" : "Astrid",
      "middleName" : null,
      "lastName" : "Alster",
      "street" : "Alsterwasserweg",
      "houseNumber" : "2",
      "street2" : "Erdgeschoss",
      "addressExtension" : null,
      "postalCode" : "20999",
      "city" : "Alsterwasser",
      "country" : "DE",
      "state" : null,
      "phone" : null,
      "mobile" : null,
      "email" : "a.alsterh@example.com",
      "salutation" : "Mrs",
      "gender" : "FEMALE"
    },
    "shippingAddress" : {
      "company" : null,
      "title" : null,
      "firstName" : "Astrid",
      "middleName" : null,
      "lastName" : "Alster",
      "street" : "Alsterwasserweg",
      "houseNumber" : "2",
      "street2" : "Erdgeschoss",
      "addressExtension" : null,
      "postalCode" : "20999",
      "city" : "Alsterwasser",
      "country" : "DE",
      "state" : null,
      "phone" : null,
      "mobile" : null,
      "email" : null,
      "salutation" : null,
      "gender" : null
    },
    "grandTotal" : {
      "currency" : "EUR",
      "amount" : 79.9
    },
    "subtotal" : {
      "currency" : "EUR",
      "amount" : 79.9
    },
    "shippingTotal" : {
      "currency" : "EUR",
      "amount" : 0
    },
    "currency" : "EUR"
  },
  "shop" : {
    "name" : "My little Cornershop"
  },
  "paymentId" : "6ab67d4a-d2fd-4745-9dda-0afb1c4be83e",
  "shopId" : "678be18f-6c17-4140-b484-c5f746bff2db",
  "errorUri" : "https://api-shop.beyondshop.cloud/checkout?errorType=API_FAILURE&recommendedUserAction=CHOOSE_DIFFERENT_PAYMENT_METHOD"
}'

Response body properties

Path Type Description

approvalUri

String

Optional URI to which the customer will be redirected after the approval of the payment. If no URI is provided, the customer will not be redirected.

paymentNote

String

Optional payment note that will appear on the order’s invoice document.

embeddedApprovalUri

String

Optional URI to the iframe that will be embedded in the checkout.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 216

{
  "approvalUri" : "https://www.app.example.com/payments/5271e303-a393-4f3d-a40c-753d299885bf/approve",
  "paymentNote" : "Please use the reference 5D746CBC94DD402EAE033F83B4AAAEE3",
  "embeddedApprovalUri" : null
}
2. Approve a payment

When receiving the approvalUri from the Beyond API, the storefront leads the customer to a payment approval page. If an embeddedApprovalUri is provided instead, the payment approval page is displayed as an iframe. On this payment approval page, the customer needs to approve/cancel the payment. The customer decision is forwarded from the payment approval page to the app. The app then needs to inform the payment gateway about the decision. To do so, the payment approval page redirects to an endpoint of the app, which notifies the payment gateway. Depending on the decision of the customer, either approval or cancelation of the payment, the payment gateway then provides a returnUri. The payment app needs to respond with a redirect to this URI.

2a. Successful payment

If the app informs the payment gateway that the customer approved the payment, the payment gateway will provide the above-mentioned returnUri to which the customer will be redirected by the app. In case of an approved payment, the returnUri is the successUri as shown below:

Required scopes

paym:m

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/payments/b9beec9d-7790-459a-b5bf-e933710d2aeb/approve' -i -X POST \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

returnUri

String

The URI to which the app will redirect the customer after the approval, cancelation or failure of the payment.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 72

{
  "returnUri" : "https://api-shop.beyondshop.cloud/checkout/success"
}

The app then redirects the customer to this URI, e.g. an order success page provided by the payment gateway.

2b. Canceled payment

One reason for an unsuccessful payment can be the customer explicitly choosing to terminate the payment flow in the approval stage. In this case, the app informs the payment gateway that the payment is canceled by calling the /payments/{paymentId}/cancel endpoint. The payment gateway will then provide a returnUri to which the customer will be redirected by the app. In case of a canceled payment, the returnUri is the cancelUri as shown below:

Required scopes

paym:m

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/payments/8f06b994-47c1-4e04-9cb6-aa80489ba03b/cancel' -i -X POST \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

returnUri

String

The URI to which the app will redirect the customer after the approval, cancelation or failure of the payment.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 71

{
  "returnUri" : "https://api-shop.beyondshop.cloud/checkout/cancel"
}

The app then redirects the customer to this URI, e.g. back to the last checkout step.

2c. Failed payment

If an error occurs during payment approval or cancelation, the payment app can also fail the payment by calling the /payments/{paymentId}/fail endpoint. A transition to the FAILED status is possible from APPROVED, CAPTURE_PENDING or directly from PENDING. In this case, the app should provide error information to the payment gateway. Although passing this information is optional, it is highly recommended.

Required scopes

paym:m

Request body properties

Path Type Description Constraints

approvalFailureType

String

The kind of error that occurred. Can be one of API_FAILURE or THREE_D_SECURE_FAILURE. Defaults to API_FAILURE.

recommendedUserAction

String

The recommended action for the customer. Can be one of RETRY or CHOOSE_DIFFERENT_PAYMENT_METHOD. Defaults to CHOOSE_DIFFERENT_PAYMENT_METHOD.

paymentErrorCode

String

An error code defined by the app to specify the problem.

Length must be between 0 and 512 inclusive

paymentErrorMessage

String

A message to further explain the problem that occurred.

Length must be between 0 and 1024 inclusive

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/payments/cdc519c3-7022-4f86-9898-6a9d68018e0e/fail' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{
  "approvalFailureType": "API_FAILURE",
  "recommendedUserAction": "RETRY",
  "paymentErrorCode": "payment-app-specific-error-code",
  "paymentErrorMessage": "An error message explaining the payment app specific error situation."
}'

Response body properties

Path Type Description

returnUri

String

The URI to which the app will redirect the customer after the approval, cancelation or failure of the payment.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 278

{
  "returnUri" : "https://api-shop.beyondshop.cloud/checkout/cancel?errorType=API_FAILURE&recommendedUserAction=RETRY&paymentErrorCode=payment-app-specific-error-code&paymentErrorMessage=An%20error%20message%20explaining%20the%20payment%20app%20specific%20error%20situation."
}

The payment gateway then provides a returnUri to which the payment app should redirect the customer. If this also fails, the app should fall back to the errorUri it received from the payment gateway upon creation of the payment to redirect the customer to the checkout.

3. Capture a payment

Besides the approval of the customer, the payment needs to be captured. This capturing is triggered by the payment gateway via a request towards the app. The payment app needs to respond with the current status of the payment. If the payment gateway receives the confirmation that the payment is paid, the payment is captured and the payment was successful, as seen in the following POST request:

Request body properties

Path Type Description

shopId

String

The unique identifier of the shop.

Example request

$ curl 'https://app.example.com/api/payments/73b9b1c7-004a-45c1-b50a-821af85479a5/capture' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -d '{
  "shopId" : "7b233e6c-a18f-4f32-b25c-412bad2cc373"
}'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 34

{
  "paymentStatus" : "CAPTURED"
}
Set a payment status

In some cases, the payment app might not be able to directly report the status of the payment as paid when the payment is captured. For example, if the payment request has been accepted but the process in the background is still in progress. The app then needs to inform the payment gateway about changes of the payment status. This can be done via a POST request:

Required scopes

paym:m

Request body properties

Path Type Description

paymentStatus

String

The status of the payment. Can be one of PENDING, APPROVED, CANCELED, CAPTURED, CAPTURE_PENDING, PAID, or FAILED, depending on the former status of the payment.

externalPaymentId

String

External payment reference that might be generated by the payment provider (optional).

externalPaymentUri

String

Link to the payment in a payment provider’s back-office (optional).

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/payments/b5908571-ef78-4d40-ab69-a177b4fefe58/status' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{"paymentStatus":"APPROVED","externalPaymentId":"transactionFDDD60A4AFBC445AAEB81C54C1355E74","externalPaymentUri":"https://example.com/transactions/transactionFDDD60A4AFBC445AAEB81C54C1355E74"}'

Response body properties

Path Type Description

paymentStatus

String

The status of the payment. Can be one of PENDING, APPROVED, CANCELED, CAPTURED, CAPTURE_PENDING, PAID, or FAILED, depending on the former status of the payment.

externalPaymentId

String

External payment reference that might be generated by the payment provider (optional).

externalPaymentUri

String

Link to the payment in a payment provider’s back-office (optional).

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 210

{
  "paymentStatus" : "APPROVED",
  "externalPaymentId" : "transactionFDDD60A4AFBC445AAEB81C54C1355E74",
  "externalPaymentUri" : "https://example.com/transactions/transactionFDDD60A4AFBC445AAEB81C54C1355E74"
}

Refunds

If an order or a single item of an order has been canceled, the respective payment needs to be refunded. This can be done via a full or a partial refund.

Request body properties

Path Type Description

shopId

String

The unique identifier of the shop.

refundAmount

Object

The amount to be refunded with currency unit.

Example request

$ curl 'https://app.example.com/api/payments/06597ede-8617-4b4f-8a0c-22042eea31ae/refund' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -d '{
  "shopId" : "0324d5ce-8491-4c01-a785-a33f574a24de",
  "refundAmount" : {
    "currency" : "EUR",
    "amount" : 10
  }
}'

Example response

HTTP/1.1 200 OK

Support

Any questions left? Get in touch with us!

Explore more

Need more ideas? Here we go:

Social commerce

Enable merchants to use social media platforms like Facebook or blogging platforms to showcase their products. You can e.g. do so by putting together a custom catalog and redirecting customers directly to a shop. This way merchants can advertise with just a few clicks.

A few of the endpoints to achieve this:

HTTP verb Endpoint

GET

/products

GET

/categories

POST

/carts

PUT

/carts/{cartId}/line-items/{lineItemId}

POST

/carts/{cartId}/order

GET

/legal-content

Shipping

Enable merchants to print shipping labels, automate parts of their shipping process, track the status of orders, or implement notifications. Additionally, you can aggregate address and weight information to generate shipping labels, or help merchants spot issues with orders that have been pending for too long. This way you can facilitate the shipping of goods for merchants.

A few of the endpoints to achieve this:

HTTP verb Endpoint

GET

/orders

GET

/products/{productId}

GET

/orders/{orderId}

GET

/orders/{orderId}/processes/shippings

Accounting

Enable merchants to track payments more easily, spot unpaid orders, or quickly evaluate the performance of their shop. You can e.g. offer notifications for payments that have been pending for too long or monitor single orders. What’s more, aggregating the turnover from orders in a specific timeframe, or separately displaying net and gross orders can help the merchant extract relevant accounting information more comfortably.

A few of the endpoints to achieve this:

HTTP verb Endpoint

GET

/orders

GET

/orders/{orderId}

GET

/orders/{orderId}/processes

PUT

/orders/{orderId}/order-note

Content optimization and marketing

Enable merchants to give their product descriptions and collections an SEO check, or help them with translation. Improve product names and descriptions, and immediately update a shop. Rearrange and create collections for a better UX, or for seasonal offers. With all that you can support merchants in terms of marketing and help them stand out in search engine results and advertising campaigns.

A few of the endpoints to achieve this:

HTTP verb Endpoint

GET

/products

PATCH

/products/{productId}

GET

/products/{productId}

GET

/categories

POST

/categories

PUT

/categories/{categoryId}

Legal service

Enable automatic updates and notifications for everything related to legal content. Retrieve the legal content that merchants display to their customers, give it a check and, if you have the merchant’s consent, improve it. You can also create templates and update certain variables at regular intervals. This way a shop’s legal documents like terms and conditions, and imprint can be handled more easily and kept up to date.

A few of the endpoints to achieve this:

HTTP verb Endpoint

GET

/legal-content

PUT

/legal-content/{name}

Point of sale (POS)/marketplace

Enable automatic stock level tracking and easy stock management for merchants. Retrieve the products a shop offers at regular intervals to maintain an up-to-date list. Check and update stock levels on every purchase. Notify merchants if supply runs low or make suggestions for reordering or producing more. This way you help merchants avoid revenue loss due to insufficient stock levels, and optimize the amounts they’d like to keep in stock.

A few of the endpoints to achieve this:

HTTP verb Endpoint

GET

/products

GET

/products/{productId}

GET

/products/{productId}/availability

PATCH

/products/{productId}

POST

/products/{productId}/availability/adjust-available-stock

Sales analytics

Enable custom analytics that give merchants the full picture of how well certain parts of their shop are performing. Aggregate information from orders to generate bestseller lists, generate graphs of a shop’s performance over time, or use zip codes to check what regions a shop is most popular in. This way you can present data in a more approachable way to merchants, and thus help them evaluate advertising campaigns, reconsider their product range, or plan expansions.

A few of the endpoints to achieve this:

HTTP verb Endpoint

GET

/products

GET

/orders

GET

/categories

Image service

Enable immediate editing of product images, or connect a shop with image websites. You can offer filtering capabilities, and put the edited pictures back into the shop, offer insertion of new images, or create whole slideshows and collages from the available product images. You can even integrate with platforms like Instagram, and give the merchant the possibility to bring images over to their shop, or reversely get product images out on different platforms. This way you can make it easier for merchants to customize the visual appearance of their shop, and help them with all tasks revolving the presentation of their products.

A few of the endpoints to achieve this:

HTTP verb Endpoint

GET

/products

GET

/products/{productId}/images

POST

/products/{productId}/images

DELETE

/products/{productId}/images/{imageId}

Enterprise Management Systems (EMS)

Enable a comprehensive overview of a shop’s performance and all related workflows by providing a complete system. Add and delete products or optimize product descriptions. Give an even more detailed insight by retrieving orders, calculating turnover, or notifying merchants about unpaid orders. Stock management and customer support can just as well be part of the system. This way parts of the business workflows can be automated, merchants can be kept up to date about the performance of the shop, and shop management as a whole can be facilitated.

A few of the endpoints to achieve this:

HTTP verb Endpoint

GET

/products

GET

/products/{productId}

POST

/products

DELETE

/products/{productId}

GET

/orders

API Reference

The following sections provide you with all the required information on API resources, operations, and usage.

Change Log

This change log covers significant updates and changes to the Beyond REST API.

2019-10-10

Remove

2019-10-08

Update

2019-08-19

Deprecate

The product-view resource (/product-view/products/search/find-by-query) to filter products is deprecated and will be removed on 1st November 2019.

2019-08-15

New

Deprecate

  • The field invoiceCancellationNote in List order settings and Update order settings is deprecated due to misspelling and will be removed on 1st October 2019. Please use invoiceCancelationNote instead. For the transition period both fields are supported with invoiceCancelationNote having precedence.

2019-08-01

Update

Remove

  • Passing the paid amount with the set status call (POST /payments/{paymentId}/status) was removed.

  • The payment statuses OVERPAID and UNDERPAID were removed.

2019-07-18

Deprecate

The product-settings resource (/product-settings) to manage product related settings is deprecated and will be removed on 1st October 2019.

2019-07-16

Update

2019-06-28

Deprecate

Passing the paid amount with the set status call (POST /payments/{paymentId}/status) is deprecated and will be removed alongside the payment statuses OVERPAID and UNDERPAID on 1st August 2019:

  • The payment statuses OVERPAID and UNDERPAID are deprecated. Setting a payment to one of these statuses results in a FAILED payment.

  • Passing a paid amount with the payment set status call will result in a FAILED payment, if the paid amount does not match the amount of the payment.

2019-06-19

New

Update

2019-05-22

New

Update

  • Added sendMail property to Create return processes . Is false by default if not set in the request.

  • Upload shop image received the Content-Type image (in addition to application/json. What’s more the endpoint now handles the label invoice logo (in addition to logo). Uploading an invoice logo requires the exact measures 900x300, otherwise the upload will not work.

Deprecate

The following endpoints are deprecated for now, but will be moved to Order settings in the near future:

  • Show invoice number configuration details (GET /configuration/invoice-number)

  • Modify complete invoice number configuration (PUT /configuration/invoice-number)

  • Update invoice number configuration partially (JSON) (PATCH /configuration/invoice-number)

  • Show order number configuration details (GET /configuration/order-number)

  • Modify complete order number configuration (PUT /configuration/order-number)

  • Update order number configuration partially (JSON) (PATCH /configuration/order-number)

2019-04-23

New

  • Added Events which explains how applications can receive information about customer actions in ePages online shops.

2019-04-17

New

2019-03-08

Deprecate

  • List products by category (GET /product-view/products/search/find-by-category)

2019-03-06

Update

2019-02-28

Update

2019-02-26

Update

2019-02-21

New

2019-01-15

New

Update

  • Added property captureWorkflow to payment method definitions.

2018-12-18

Update

  • Added optional field dependentLocality to billing and shipping address properties.

  • Added payment status for prepayment-style payments (e.g. OVERPAID, UNDERPAID). This allows passing the actual amount paid to the Set payment status with amount endpoint (first implementation step).

2018-11-20

New

Update

  • Added field paymentNote property to payments.

  • Create payment provides an errorUri to the payment app.

2018-11-12

New

2018-11-07

New

Update

2018-10-30

Update

2018-10-29

New

2018-10-18

Update

2018-09-11

Update

2018-08-28

New

Update

2018-08-14

Update

2018-07-17

New

2018-06-19

New

2018-06-05

New

Update

2018-05-22

Update

  • Added minimumOrderValue property to cart’s payload.

2018-04-10

New

Update

  • Enhanced official apps to carry additional configuration data used for payment app creation.

2018-03-29

New

2018-03-13

New

Authentication

Create a JsonWebToken from Refresh Token

A POST request is used to create a JsonWebToken from a refresh token.

Request parameters

Parameter Description

grant_type

OAuth2 grant type. Use client_credentials for client credentials flow, authorization_code for authorization code flow, and refresh_token to refresh an access token.

refresh_token

The token that can be used to obtain a renewed access token when the current token has expired. Required for the refresh_token grant type.

Request header properties

Name Description

Authorization

The HTTP Basic Authorization header containing the OAuth 2.0 client credentials (client_id:client_secret).

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/oauth/token' -i -u 'sample-client:d40668ef-2258-4e11-b925-e0a1ea83f34c' -X POST \
    -d 'grant_type=refresh_token&refresh_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.eyJ1c2VyX25hbWUiOiJ1c2VyIiwic2NvcGUiOlsicHJvZDpyYyJdLCJhdGkiOiJiMjZkNjgyNC05MTNkLTQwODAtOGVmYy1kYjlhNzI1OWE1OTQiLCJ0ZW5hbnRJZCI6MTQzOCwiZXhwIjoxNTczNzMwNDg4LCJpYXQiOjE1NzExMzg0ODgsInVzZXJJZCI6IjY4OGI5NGRjLWM1ZGUtNGQ2Ni1hMDhjLWRlNGVjYjRjMjljOSIsImp0aSI6Ijk2ODhhNDYwLWM0Y2QtNGIyZC1hYzRmLWRmZTBjZWI5MWI3NSIsImNsaWVudF9pZCI6InNhbXBsZS1jbGllbnQiLCJ1c2VybmFtZSI6InVzZXIifQ.hpbs-dPDr9xYFsDyMc_plV1qA2yLXwwkUssP1HW2J0_OLMiWzoCHDJ6TF_1hiI9H9ENQgjQkfA0zm5D6PA2tAOlLHVgrBOLmBs-CMuqOy8bmYC3USSWIwBMHmys7_h0MEFut3JNy2gnqhhzYtMADKVY0ttfFB3_TGpnt32BlhIX8E4j2YDqhN4Zy3KmSgJwBcjgP9cu2bKWhgErKnsu3msO-zjMaWamWASZSTSOvqCDNj1KiiSMRHUWMdEsaz6HGgvMoPsehMCen1hoey9uiV2g-8sUeGhSvWaPoIG1kr7CwRuSU2Ubr8zO-lP0eJDEZ-N7gE3p4Xt07rkaPml7-WA'

Response body properties

Path Type Description

refresh_token

String

The token that can be used to obtain a renewed access token.

userId

String

The unique identifier of the user the token was issued for.

username

String

The username that identifies the user the token was issued for.

access_token

String

The encoded JsonWebToken to access the resource.

tenantId

Number

The unique identifier of the tenant.

token_type

String

Represents how an accessToken will be generated and presented for accessing a resource. Always issued as Bearer.

iat

Number

The timestamp when the token was created (Issued At). Displayed in seconds since the start of the Epoch. Refer to RFC 7519.

expires_in

Number

The time of token expiry in seconds. Calculated from iat.

scope

String

A space-delimited list of scopes the token is issued for.

jti

String

The unique token identifier of the token. Must be unique for each request. Refer to RFC 7519.

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1753

{
  "access_token" : "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.eyJ1c2VyX25hbWUiOiJ1c2VyIiwic2NvcGUiOlsicHJvZDpyYyJdLCJ0ZW5hbnRJZCI6MTQzOCwiZXhwIjoxNTcxMzk3Njg4LCJpYXQiOjE1NzExMzg0ODgsInVzZXJJZCI6IjY4OGI5NGRjLWM1ZGUtNGQ2Ni1hMDhjLWRlNGVjYjRjMjljOSIsImp0aSI6IjY2OGQ3YzkxLTViMzktNDc3NC1iMzA5LTQxNGYwMTY0MWM1NyIsImNsaWVudF9pZCI6InNhbXBsZS1jbGllbnQiLCJ1c2VybmFtZSI6InVzZXIifQ.VRaSGMJ-A2GY17kmZBxNP_gWnUOEjwE9R0NrqoNPQbWbdJXMB88yu6H2svwSmQq7QM6D4isLoeJblTiNj-vzaqUj8Yi5S0X_sTSK1GPgAO4i5AzmFGneKujMWE8UbCEviBeflfA0fK8uXKOwpbrXQbwc5ZttmujY2gv64f0KbZnk2VaL-HyFjWIxcwrwdmoaLJ8QLBtTsO6DxIYXyGmq7cDKT7gyeFJRPQo0Ibym73FLKAhHAXFOUTkI_8j3hQVyn1M3LZGATk_1wgUZKwmVxyLLBH04w3DFKpvaIrUJ-3RTXxtsu_bfGvo1dCg15n8wcWZ6pq9H_68-jtw2yLsYUw",
  "token_type" : "bearer",
  "refresh_token" : "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.eyJ1c2VyX25hbWUiOiJ1c2VyIiwic2NvcGUiOlsicHJvZDpyYyJdLCJhdGkiOiI2NjhkN2M5MS01YjM5LTQ3NzQtYjMwOS00MTRmMDE2NDFjNTciLCJ0ZW5hbnRJZCI6MTQzOCwiZXhwIjoxNTczNzMwNDg4LCJpYXQiOjE1NzExMzg0ODgsInVzZXJJZCI6IjY4OGI5NGRjLWM1ZGUtNGQ2Ni1hMDhjLWRlNGVjYjRjMjljOSIsImp0aSI6Ijk2ODhhNDYwLWM0Y2QtNGIyZC1hYzRmLWRmZTBjZWI5MWI3NSIsImNsaWVudF9pZCI6InNhbXBsZS1jbGllbnQiLCJ1c2VybmFtZSI6InVzZXIifQ.cRw_Dfs-QW3yanHCs5ljYTi1woU1If0dnHuN4C-y6FHmHdVN8D88PWeloanvJE8ou0Zud8wIS2bVdVHkRLWwPUccq-hv1laGT23ZrEkn6TgVohBwy8xCSh2acauftz1fL9aAMbddALtPHtbhN7HRTxDfbycrLj-0BZpmFD5etLTVqqzK1AZ-3Ywds6bWSSSwmFdhwwpe7JxUm8Lm2cnwvST06KCQFl7gJZEvp8SjXcI22xFY4sZzYo8p7-1KCY3hiE-zqHgcX5nI2_JqO98X2j1GM5obtzMrhm2u-rjDqLz24OOeDhtoYJ4Qjk3xRRL1_jwa5I-5r8OQDpljpf884w",
  "expires_in" : 259199,
  "scope" : "prod:rc",
  "tenantId" : 1438,
  "iat" : 1571138488,
  "userId" : "688b94dc-c5de-4d66-a08c-de4ecb4c29c9",
  "username" : "user",
  "jti" : "668d7c91-5b39-4774-b309-414f01641c57"
}

Create a JsonWebToken from Client Credentials

A POST request is used to create a JsonWebToken using the client_credentials grant type.

Request parameters

Parameter Description

grant_type

OAuth2 grant type. Use client_credentials for client credentials flow, authorization_code for authorization code flow, and refresh_token to refresh an access token.

Request header properties

Name Description

Authorization

The HTTP Basic Authorization header containing the OAuth 2.0 client credentials (client_id:client_secret).

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/oauth/token' -i -u 'clientId-1:password' -X POST \
    -d 'grant_type=client_credentials'

Response body properties

Path Type Description

access_token

String

The encoded JsonWebToken to access the resource.

tenantId

Number

The unique identifier of the tenant.

token_type

String

Represents how an accessToken will be generated and presented for accessing a resource. Always issued as Bearer.

iat

Number

The timestamp when the token was created (Issued At). Displayed in seconds since the start of the Epoch. Refer to RFC 7519.

expires_in

Number

The time of token expiry in seconds. Calculated from iat.

scope

String

A space-delimited list of scopes the token is issued for.

jti

String

The unique token identifier of the token. Must be unique for each request. Refer to RFC 7519.

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 774

{
  "access_token" : "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.eyJzY29wZSI6WyJwcm9kOmNyIl0sInRlbmFudElkIjoxNDM4LCJleHAiOjE1NzExODE2OTIsImlhdCI6MTU3MTEzODQ5MiwianRpIjoiZDliMGRiMzgtMjI0Zi00MjY0LWE2NWEtNDhmNDcwMTRjOGE1IiwiY2xpZW50X2lkIjoiY2xpZW50SWQtMSJ9.A7FF_Ti9vgqMcT4phk9yWIAOzKw2qGNrlpngLQBqTu6DDhYKDXHGbUZJcHehqTUoW9olz_V-KmUN2mMzW_OFmcxQV3zYMG_7CgKE_cIF-UcJiNNFvbZDPpKNdggu5OdxB00F4UYeWo9cDjgkpYQVDWXLlmCTSOf3bGEljHE8teLcRumYTJjVJdurz_osg27XIIa3_isXEHWz0Ci8AcnPF2SnBgEJtbDa0SZygYvg9MQmf5y_qS4mG1sYCKTpEubIlvOzZTeiKYZJTlmTPlyA3mkRpCyK3MkSK4XAJu2zzNczEeZQFoAp_Slw5g6KVvaXElIj8rvsrTfMpNrbWQ1INw",
  "token_type" : "bearer",
  "expires_in" : 43199,
  "scope" : "prod:cr",
  "tenantId" : 1438,
  "iat" : 1571138492,
  "jti" : "d9b0db38-224f-4264-a65a-48f47014c8a5"
}

Carts

The cart resources are used to manage the carts of a shop. A cart allows customers to pick products from a shop and store them to be bought now or at a later time. The cart can contain a single or various line items. The cart also holds the feature for setting the billing address, the shipping address and shipping zone as well as the payment method.

Create cart

A POST request is used to create a cart.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts' -i -X POST \
    -H 'Accept: application/hal+json'

Example response

HTTP/1.1 201 Created
Location: https://api-shop.beyondshop.cloud/api/carts/1c3fb0f9-494d-40c9-bd25-8d40b6f2177b
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 4825

{
  "_id" : "1c3fb0f9-494d-40c9-bd25-8d40b6f2177b",
  "lineItems" : [ ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "shipping-method" : {
        "_id" : "0cd03ff0-344e-4454-9935-fbdd56326dcf",
        "name" : "Standard",
        "description" : "Standard shipping. Delivery within 3-4 days.",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : null,
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 19.99
        },
        "weightBasedPrice" : null,
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/c8f82588-1669-4c4e-87cb-049db4d98ca4/shipping-methods/0cd03ff0-344e-4454-9935-fbdd56326dcf"
          }
        }
      }
    }
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "payment-method" : {
        "_id" : "870057c6-06d0-4389-88d1-ee2f7ea85123",
        "name" : "Converge",
        "description" : "Pay by Converge.",
        "officialName" : "Converge",
        "officialDescription" : "Pay by Converge.",
        "taxClass" : "REGULAR",
        "discountOrFee" : {
          "type" : "ABSOLUTE",
          "absoluteValue" : {
            "taxModel" : "GROSS",
            "currency" : "EUR",
            "amount" : 2
          },
          "percentageValue" : null
        },
        "position" : 1,
        "serviceableCountries" : [ "DE" ],
        "minimumOrderValue" : null,
        "activated" : true,
        "activeLogoSet" : null,
        "onlinePayment" : false,
        "workflow" : null,
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/870057c6-06d0-4389-88d1-ee2f7ea85123"
          },
          "payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/870057c6-06d0-4389-88d1-ee2f7ea85123"
          },
          "deactivate-payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/870057c6-06d0-4389-88d1-ee2f7ea85123/deactivate"
          },
          "payment-method-definition" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/870057c6-06d0-4389-88d1-ee2f7ea85123/payment-method-definition"
          }
        }
      }
    }
  },
  "billingAddress" : null,
  "shippingAddress" : null,
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 21.99
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 21.99
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 21.99
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "taxes" : [ ],
  "taxable" : true,
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 4
  },
  "mustAcceptTermsAndConditions" : false,
  "weight" : 0,
  "checkoutState" : {
    "shippingMethodValid" : true,
    "shippingMethodSelectable" : true,
    "paymentMethodValid" : true,
    "paymentMethodSelectable" : true,
    "billingAddressSet" : false,
    "priceValidToOrder" : false,
    "paymentTransactionStatus" : "NO_APPROVAL_NEEDED",
    "readyToOrder" : false
  },
  "customerEmail" : null,
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/1c3fb0f9-494d-40c9-bd25-8d40b6f2177b"
    },
    "line-items" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/1c3fb0f9-494d-40c9-bd25-8d40b6f2177b/line-items"
    },
    "shipping-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/1c3fb0f9-494d-40c9-bd25-8d40b6f2177b/shipping-methods"
    },
    "shipping-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/1c3fb0f9-494d-40c9-bd25-8d40b6f2177b/shipping-methods/default"
    },
    "shipping-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/1c3fb0f9-494d-40c9-bd25-8d40b6f2177b/shipping-methods/current"
    },
    "payment-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/1c3fb0f9-494d-40c9-bd25-8d40b6f2177b/payment-methods"
    },
    "payment-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/1c3fb0f9-494d-40c9-bd25-8d40b6f2177b/payment-methods/default"
    },
    "payment-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/1c3fb0f9-494d-40c9-bd25-8d40b6f2177b/payment-methods/current"
    },
    "billing-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/1c3fb0f9-494d-40c9-bd25-8d40b6f2177b/billing-address"
    },
    "shipping-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/1c3fb0f9-494d-40c9-bd25-8d40b6f2177b/shipping-address"
    }
  }
}

Show cart details

A GET request is used to retrieve the details of a cart.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/4887e7ee-7091-4e3f-9f51-3030fd20b3cf' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json'

Response body properties

Path Type Description

_id

String

The unique identifier of the cart.

lineItems[]._id

String

The unique identifier of the product line item.

lineItems[]._ref

String

The ID of the associated item (in case of _type=PRODUCT the product ID).

lineItems[]._type

String

The type of the line item (always PRODUCT for product line items).

lineItems[].name

String

The name of the line item.

lineItems[]._embedded.product

Object

The product-related details.

lineItems[]._embedded.product._id

String

The immutable, unique identifier of the requested resource.

lineItems[]._embedded.product.sku

String

The SKU of the product line item.

lineItems[]._embedded.product.essentialFeatures

String

The essential product properties. Shown in the cart and checkout. In Germany mandatory field in online shops according to §312j Abs. 2 BGB (German Civil Code).

lineItems[]._embedded.product.variationAttributeValues

Array

The collection of variation attribute values.

lineItems[]._embedded.product.variationAttributeValues[].displayName

String

The name of the variation attribute.

lineItems[]._embedded.product.variationAttributeValues[].value

String

The value of the variation attribute.

lineItems[]._embedded.product._links.product

Object

The link to the product.

lineItems[]._embedded.product._links.default-image-data

Object

The download URL of the default image.

lineItems[].quantity

Number

The value of the quantity of the single line item.

lineItems[].singleItemPrice.taxModel

String

The tax model of the single line item price.

lineItems[].singleItemPrice.amount

Number

The amount of the single line item price.

lineItems[].singleItemPrice.currency

String

The currency of the single line item price.

lineItems[].lineItemPrice.taxModel

String

The tax model of the line item total price.

lineItems[].lineItemPrice.amount

Number

The amount of the line item total price.

lineItems[].lineItemPrice.currency

String

The currency of the line item total price.

lineItems[].lineItemTax.taxRate

Number

The tax rate of the line item.

lineItems[].lineItemTax.taxClass

String

The tax class of the line item. Can be REGULAR, REDUCED, or EXEMPT.

lineItems[].lineItemTax.amount

Number

The tax amount of the line item.

lineItems[].lineItemTax.currency

String

The currency of the line item.

lineItems[]._links.self.href

String

The self URI of the product line item.

shippingLineItem._embedded.shipping-method

Object

The line items of the shipping method.

shippingLineItem.lineItemTaxes

Array

The tax information for the shipping line item. The array contains one item per tax class.

shippingLineItem.lineItemPrice.taxModel

String

The tax model of the price for this shipping line item.

shippingLineItem.lineItemPrice.amount

Number

The amount of the price for this shipping line item.

shippingLineItem.lineItemPrice.currency

String

The currency of the price for this shipping line item.

paymentLineItem._embedded.payment-method

Object

Refer to Show payment method details for item documentation.

paymentLineItem.lineItemTaxes

Array

The tax information for the payment line item. The array contains one item per tax class.

paymentLineItem.lineItemPrice.taxModel

String

The tax model of the payment line item price.

paymentLineItem.lineItemPrice.amount

Number

The amount of the payment line item price.

paymentLineItem.lineItemPrice.currency

String

The currency of the payment line item price.

billingAddress

Object

The billing address of the cart. Refer to Set cart billing address for item documentation.

billingAddress.displayAddressLines

Array

The applicable billing address of the cart to be displayed.

shippingAddress

Object

The shipping address that applies to the cart. Defaults to billing address if no shipping address is set. Refer to Set cart shipping address for item documentation.

shippingAddress.displayAddressLines

Array

The applicable shipping address of the cart to be displayed.

grandTotal

Object

The total price to be paid including product price, shipping, and tax.

subtotal

Object

The subtotal of the product line items.

netTotal

Object

The total net amount of the cart.

taxTotal

Object

The total tax amount.

taxable

Boolean

Indicates if a tax applies for the cart. Can be true or false.

taxes

Array

The tax amount per tax class.

taxes[*].taxClass

String

The tax class that applies for the cart.

taxes[*].taxRate

Number

The tax rate of this tax class.

taxes[*].amount

Number

The tax amount of this tax class.

taxes[*].currency

String

The currency for this tax amount.

balanceDue

Object

The outstanding balance of the amount to be paid.

minimumOrderValue

Object

The minimum value of the cart so that this payment method can be used.

mustAcceptTermsAndConditions

Boolean

Indicates if the customer has to explicitly consent to the terms and conditions before buying something.

weight

Number

The total weight of products in the cart. A product’s weight defaults to 0 if not set.

checkoutState.readyToOrder

Boolean

Indicates if this cart is ready to create an order. Can be true or false.

checkoutState.shippingMethodValid

Boolean

Indicates if the shipping method for this cart is valid.

checkoutState.shippingMethodSelectable

Boolean

Indicates if the shipping method for this cart can be selected.

checkoutState.paymentMethodValid

Boolean

Indicates if the payment method for this cart is valid. Can be true or false.

checkoutState.paymentMethodSelectable

Boolean

Indicates if the payment method for this cart can be selected. Can be true or false.

checkoutState.billingAddressSet

Boolean

Indicates if the billing address for the cart is set. Can be true or false.

checkoutState.priceValidToOrder

Boolean

Indicates if the cart sum is valid to create an order. Can be true or false.

customerEmail

Null

The customer’s email address that is assigned to the cart.

checkoutState.paymentTransactionStatus

String

The state of the payment transaction of this cart. Can be one of NO_APPROVAL_NEEDED, APPROVAL_PENDING, or APPROVED.

_links

Object

See Hypermedia

paymentLineItem._embedded.payment-method._id

String

The immutable, unique identifier of the requested resource.

paymentLineItem._embedded.payment-method.position

Number

The sorting position of the payment method in the merchant’s cockpit in relation to other payment methods.

paymentLineItem._embedded.payment-method.officialName

String

The official name of the payment method chosen by the merchant during setup.

paymentLineItem._embedded.payment-method.officialDescription

String

The official description of the payment method chosen by the merchant during setup.

paymentLineItem._embedded.payment-method.name

String

The name of the payment method that is used during checkout.

paymentLineItem._embedded.payment-method.description

String

Description of the payment method that is used during checkout.

paymentLineItem._embedded.payment-method.activated

Boolean

Indicates if a payment method is active. Can be true or false.

paymentLineItem._embedded.payment-method.taxClass

String

The tax class. Can be REGULAR, REDUCED, or EXEMPT.

paymentLineItem._embedded.payment-method.discountOrFee

Object

The details about the fee to be payed or discount to be granted for this payment method.

paymentLineItem._embedded.payment-method.discountOrFee.type

String

The discount or fee can be an absolute or a percentage based value. Can be one of PERCENTAGE or ABSOLUTE. ABSOLUTE contains another attribute absoluteValue with a positive or negative price. PERCENTAGE contains another attribute percentageValue with a negative or positive percentage value.

paymentLineItem._embedded.payment-method.serviceableCountries

Array

The list of target countries this payment method can be used in.

paymentLineItem._embedded.payment-method.minimumOrderValue

Null

The minimum value of the cart so that this payment method can be used.

paymentLineItem._embedded.payment-method.onlinePayment

Boolean

Indicates if the payment method is an online payment. Can be true or false.

paymentLineItem._embedded.payment-method.activeLogoSet

Null

The name of the currently selected logo set. Can be TILE, DETAILS, LIST, or STOREFRONT. (official is always the fallback).

paymentLineItem._embedded.payment-method.workflow

Null

The payment workflow for the current payment. Can be one of PAYMENT_ON_SELECTION, EMBEDDED_ON_SELECTION, PAYMENT_ON_BUY, or EMBEDDED_ON_BUY.

paymentLineItem._embedded.payment-method._links

Object

See Hypermedia

shippingLineItem._embedded.shipping-method._id

String

The immutable, unique identifier of the requested resource.

shippingLineItem._embedded.shipping-method.weightBasedPrice

Null

The price depending on the package weight (optional).

shippingLineItem._embedded.shipping-method.freeShippingValue

Null

Once a customer reaches this amount (excluding payment fee) this shipping method is free of charge.

shippingLineItem._embedded.shipping-method.position

Number

The sorting position of the shipping method in the merchant’s cockpit in relation to other shipping methods.

shippingLineItem._embedded.shipping-method.name

String

The name of the shipping method.

shippingLineItem._embedded.shipping-method.description

String

The description of the shipping method.

shippingLineItem._embedded.shipping-method.taxClass

String

The tax class. Can be REGULAR, REDUCED, or EXEMPT.

shippingLineItem._embedded.shipping-method.freeShippingValue

Null

Once a customer reaches this amount (excluding payment fee) this shipping method is free of charge.

shippingLineItem._embedded.shipping-method.fixedPrice

object

The fixed price for the shipping method irrespective of weight, dimensions, etc.

shippingLineItem._embedded.shipping-method._links

Object

See Hypermedia

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 8193

{
  "_id" : "4887e7ee-7091-4e3f-9f51-3030fd20b3cf",
  "lineItems" : [ {
    "_type" : "PRODUCT",
    "_id" : "d26d5feb-41ed-430e-8c30-4b2e5618bf71",
    "_ref" : "c6aee80c-49bc-4444-b57e-b87761902b57",
    "name" : "High Protein Power Bar (Pack of 5)",
    "quantity" : 1,
    "singleItemPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 4.95
    },
    "lineItemPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 4.95
    },
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 0.9405
    },
    "_embedded" : {
      "product" : {
        "_id" : "c6aee80c-49bc-4444-b57e-b87761902b57",
        "sku" : "EB001",
        "essentialFeatures" : "Preservative-free. No added sweeteners. Vegan.",
        "variationAttributeValues" : [ {
          "displayName" : "flavor",
          "value" : "Salted Caramel"
        } ],
        "_links" : {
          "product" : {
            "href" : "https://api-shop.beyondshop.cloud/api/product-view/products/c6aee80c-49bc-4444-b57e-b87761902b57?locale=undefined-UNDEFINED"
          },
          "default-image-data" : {
            "href" : "https://api-shop.beyondshop.cloud/api/http:/your.image.hoster.com/randomimage.png"
          }
        }
      }
    },
    "_links" : {
      "self" : {
        "href" : "https://api-shop.beyondshop.cloud/api/carts/4887e7ee-7091-4e3f-9f51-3030fd20b3cf/line-items/d26d5feb-41ed-430e-8c30-4b2e5618bf71"
      }
    }
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.0,
      "currency" : "EUR",
      "amount" : 0
    } ],
    "_embedded" : {
      "shipping-method" : {
        "_id" : "7475390e-0df3-4154-bc46-1908a654cdd5",
        "name" : "Standard",
        "description" : "Standard shipping. Delivery within 3-4 days.",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : null,
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 19.99
        },
        "weightBasedPrice" : null,
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/a67c30a6-8c9d-45aa-98d8-f9ea01ee6f43/shipping-methods/7475390e-0df3-4154-bc46-1908a654cdd5"
          }
        }
      }
    }
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.0,
      "currency" : "EUR",
      "amount" : 0
    } ],
    "_embedded" : {
      "payment-method" : {
        "_id" : "2e31d100-d749-42b4-b160-6032fcfef586",
        "name" : "Converge",
        "description" : "Pay by Converge.",
        "officialName" : "Converge",
        "officialDescription" : "Pay by Converge.",
        "taxClass" : "REGULAR",
        "discountOrFee" : {
          "type" : "ABSOLUTE",
          "absoluteValue" : {
            "taxModel" : "GROSS",
            "currency" : "EUR",
            "amount" : 2
          },
          "percentageValue" : null
        },
        "position" : 1,
        "serviceableCountries" : [ "DE" ],
        "minimumOrderValue" : null,
        "activated" : true,
        "activeLogoSet" : null,
        "onlinePayment" : false,
        "workflow" : null,
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/2e31d100-d749-42b4-b160-6032fcfef586"
          },
          "payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/2e31d100-d749-42b4-b160-6032fcfef586"
          },
          "deactivate-payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/2e31d100-d749-42b4-b160-6032fcfef586/deactivate"
          },
          "payment-method-definition" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/2e31d100-d749-42b4-b160-6032fcfef586/payment-method-definition"
          }
        }
      }
    }
  },
  "billingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : null,
    "title" : "",
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "Erdgeschoss",
    "addressExtension" : "Hinterhof",
    "postalCode" : "20999",
    "dependentLocality" : "Seevetal",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a.alsterh@example.com",
    "phone" : "(800) 555-0102",
    "mobile" : "(800) 555-0103",
    "displayAddressLines" : [ "Astrid Agnes Alster", "Alsterwasserweg 2", "Erdgeschoss", "Hinterhof", "Seevetal", "20999 Alsterwasser", "DEUTSCHLAND" ],
    "vatId" : "123456789",
    "taxNumber" : "123-34-6789",
    "birthDate" : "1985-03-20"
  },
  "shippingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : null,
    "title" : "",
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "Erdgeschoss",
    "addressExtension" : "Hinterhof",
    "postalCode" : "20999",
    "dependentLocality" : "Seevetal",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a.alsterh@example.com",
    "phone" : "(800) 555-0102",
    "mobile" : "(800) 555-0103",
    "displayAddressLines" : [ "Astrid Agnes Alster", "Alsterwasserweg 2", "Erdgeschoss", "Hinterhof", "Seevetal", "20999 Alsterwasser", "DEUTSCHLAND" ],
    "doorCode" : "0185"
  },
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 4.95
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 26.94
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 26.94
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 26.94
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "taxes" : [ {
    "taxClass" : "REGULAR",
    "taxRate" : 0.0,
    "currency" : "EUR",
    "amount" : 0
  } ],
  "taxable" : true,
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 4
  },
  "mustAcceptTermsAndConditions" : false,
  "weight" : 190,
  "checkoutState" : {
    "shippingMethodValid" : true,
    "shippingMethodSelectable" : true,
    "paymentMethodValid" : true,
    "paymentMethodSelectable" : true,
    "billingAddressSet" : true,
    "priceValidToOrder" : true,
    "paymentTransactionStatus" : "NO_APPROVAL_NEEDED",
    "readyToOrder" : true
  },
  "customerEmail" : null,
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/4887e7ee-7091-4e3f-9f51-3030fd20b3cf"
    },
    "line-items" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/4887e7ee-7091-4e3f-9f51-3030fd20b3cf/line-items"
    },
    "shipping-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/4887e7ee-7091-4e3f-9f51-3030fd20b3cf/shipping-methods"
    },
    "shipping-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/4887e7ee-7091-4e3f-9f51-3030fd20b3cf/shipping-methods/default"
    },
    "shipping-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/4887e7ee-7091-4e3f-9f51-3030fd20b3cf/shipping-methods/current"
    },
    "payment-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/4887e7ee-7091-4e3f-9f51-3030fd20b3cf/payment-methods"
    },
    "payment-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/4887e7ee-7091-4e3f-9f51-3030fd20b3cf/payment-methods/default"
    },
    "payment-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/4887e7ee-7091-4e3f-9f51-3030fd20b3cf/payment-methods/current"
    },
    "billing-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/4887e7ee-7091-4e3f-9f51-3030fd20b3cf/billing-address"
    },
    "shipping-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/4887e7ee-7091-4e3f-9f51-3030fd20b3cf/shipping-address"
    },
    "place-order" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/4887e7ee-7091-4e3f-9f51-3030fd20b3cf/order"
    }
  }
}

Delete cart

A DELETE request is used to remove the cart.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/6680031e-09c8-457f-9077-d4508df965e7' -i -X DELETE

Example response

HTTP/1.1 204 No Content

Create order from cart

A POST request is used to create an order from the cart.

This endpoint can just be used on a cart with checkoutState.readyToOrder == true. readyToOrder does not include the availability check, so this might still fail if stock-managed products are not available.

The response contains a location header with a link to the order. Note that the order is created asynchronously and is not available immediately.

Request body properties

Path Type Description Constraints

customerComment

String

An optional comment from the customer regarding the order.

Length must be between 0 and 1000 inclusive

salesChannel

String

The sales channel for this order, such as an online shop, point of sale, or a retail store. Defaults to Unknown.

Length must be between 0 and 100 inclusive. Must not be empty

marketingChannel

String

The marketing channel for this order, such as a newsletter campaign, Google Shopping, or a Buy Button that’s implemented on a blog.

Length must be between 0 and 100 inclusive

marketingSubchannel

String

The marketing subchannel for this order, such as a specific newsletter of a newsletter campaign, e.g. a Summer Sale that’s promoted on a blog, or a Winter Special that’s promoted on Facebook.

Length must be between 0 and 100 inclusive

testOrder

Boolean

Indicates if this order is a test order. Can be true or false.

termsAndConditionsExplicitlyAccepted

Boolean

Indicates if the shop’s terms and conditions have been explicitly accepted. If explicit consent is required (see checkout settings) and not given, trying to order the cart will fail. Can be true or false.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/ec065a3a-75ea-4075-876a-258eee0f3f8b/order' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{"customerComment": "send it fast please",
  "salesChannel": "DifferentChannel",
  "marketingChannel": "Google",
  "marketingSubchannel": "Search page 2",
  "testOrder": false,
  "termsAndConditionsExplicitlyAccepted": true
}'

Example response

HTTP/1.1 202 Accepted
Location: https://api-shop.beyondshop.cloud/api/orders/search/find-order-number-by-cart-id?cartId=ec065a3a-75ea-4075-876a-258eee0f3f8b

Add single line item to cart

A POST request is used to add a line item to the cart. Currently only product line items are supported.

Request body properties

Path Type Description

_type

String

The type of the line item (always PRODUCT for product line items).

_ref

String

The ID of the associated item (in case of _type=PRODUCT the product ID).

quantity

Number

The quantity for the line item to be set. If the line item is already in the cart, the quantity is added. Defaults to one.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/133ec458-889c-4359-8b4b-bb6bf2fb17ae/line-items' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{"_type":"PRODUCT","_ref":"c5b92002-0f77-4dfd-9e4b-47496164ae01","quantity":1}'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 6556

{
  "_id" : "133ec458-889c-4359-8b4b-bb6bf2fb17ae",
  "lineItems" : [ {
    "_type" : "PRODUCT",
    "_id" : "394b8d61-74f0-437e-ae1e-1eef48bda64e",
    "_ref" : "c5b92002-0f77-4dfd-9e4b-47496164ae01",
    "name" : "High Protein Power Bar (Pack of 5)",
    "quantity" : 1,
    "singleItemPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 4.95
    },
    "lineItemPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 4.95
    },
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 0.9405
    },
    "_embedded" : {
      "product" : {
        "_id" : "c5b92002-0f77-4dfd-9e4b-47496164ae01",
        "sku" : "EB001",
        "essentialFeatures" : "Preservative-free. No added sweeteners. Vegan.",
        "variationAttributeValues" : [ {
          "displayName" : "flavor",
          "value" : "Salted Caramel"
        } ],
        "_links" : {
          "product" : {
            "href" : "https://api-shop.beyondshop.cloud/api/product-view/products/c5b92002-0f77-4dfd-9e4b-47496164ae01?locale=undefined-UNDEFINED"
          },
          "default-image-data" : {
            "href" : "https://api-shop.beyondshop.cloud/api/http:/your.image.hoster.com/randomimage.png"
          }
        }
      }
    },
    "_links" : {
      "self" : {
        "href" : "https://api-shop.beyondshop.cloud/api/carts/133ec458-889c-4359-8b4b-bb6bf2fb17ae/line-items/394b8d61-74f0-437e-ae1e-1eef48bda64e"
      }
    }
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.0,
      "currency" : "EUR",
      "amount" : 0
    } ],
    "_embedded" : {
      "shipping-method" : {
        "_id" : "fdb0d570-0093-454c-a4d3-05cd43667f3f",
        "name" : "Standard",
        "description" : "Standard shipping. Delivery within 3-4 days.",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : null,
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 19.99
        },
        "weightBasedPrice" : null,
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/3e23c6dd-930b-4918-9ee4-f79356d3ce04/shipping-methods/fdb0d570-0093-454c-a4d3-05cd43667f3f"
          }
        }
      }
    }
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.0,
      "currency" : "EUR",
      "amount" : 0
    } ],
    "_embedded" : {
      "payment-method" : {
        "_id" : "deaec550-0485-4547-ba37-cd779b59602b",
        "name" : "Converge",
        "description" : "Pay by Converge.",
        "officialName" : "Converge",
        "officialDescription" : "Pay by Converge.",
        "taxClass" : "REGULAR",
        "discountOrFee" : {
          "type" : "ABSOLUTE",
          "absoluteValue" : {
            "taxModel" : "GROSS",
            "currency" : "EUR",
            "amount" : 2
          },
          "percentageValue" : null
        },
        "position" : 1,
        "serviceableCountries" : [ "DE" ],
        "minimumOrderValue" : null,
        "activated" : true,
        "activeLogoSet" : null,
        "onlinePayment" : false,
        "workflow" : null,
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/deaec550-0485-4547-ba37-cd779b59602b"
          },
          "payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/deaec550-0485-4547-ba37-cd779b59602b"
          },
          "deactivate-payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/deaec550-0485-4547-ba37-cd779b59602b/deactivate"
          },
          "payment-method-definition" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/deaec550-0485-4547-ba37-cd779b59602b/payment-method-definition"
          }
        }
      }
    }
  },
  "billingAddress" : null,
  "shippingAddress" : null,
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 4.95
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 26.94
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 26.94
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 26.94
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "taxes" : [ {
    "taxClass" : "REGULAR",
    "taxRate" : 0.0,
    "currency" : "EUR",
    "amount" : 0
  } ],
  "taxable" : true,
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 4
  },
  "mustAcceptTermsAndConditions" : false,
  "weight" : 190,
  "checkoutState" : {
    "shippingMethodValid" : true,
    "shippingMethodSelectable" : true,
    "paymentMethodValid" : true,
    "paymentMethodSelectable" : true,
    "billingAddressSet" : false,
    "priceValidToOrder" : true,
    "paymentTransactionStatus" : "NO_APPROVAL_NEEDED",
    "readyToOrder" : false
  },
  "customerEmail" : null,
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/133ec458-889c-4359-8b4b-bb6bf2fb17ae"
    },
    "line-items" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/133ec458-889c-4359-8b4b-bb6bf2fb17ae/line-items"
    },
    "shipping-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/133ec458-889c-4359-8b4b-bb6bf2fb17ae/shipping-methods"
    },
    "shipping-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/133ec458-889c-4359-8b4b-bb6bf2fb17ae/shipping-methods/default"
    },
    "shipping-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/133ec458-889c-4359-8b4b-bb6bf2fb17ae/shipping-methods/current"
    },
    "payment-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/133ec458-889c-4359-8b4b-bb6bf2fb17ae/payment-methods"
    },
    "payment-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/133ec458-889c-4359-8b4b-bb6bf2fb17ae/payment-methods/default"
    },
    "payment-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/133ec458-889c-4359-8b4b-bb6bf2fb17ae/payment-methods/current"
    },
    "billing-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/133ec458-889c-4359-8b4b-bb6bf2fb17ae/billing-address"
    },
    "shipping-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/133ec458-889c-4359-8b4b-bb6bf2fb17ae/shipping-address"
    }
  }
}

Replace single line item

A PUT request is used to replace only one line item in the cart.

Request body properties

Path Type Description

_type

String

The type of the line item (always PRODUCT for product line items).

_ref

String

The ID of the associated item (in case of _type=PRODUCT the product ID).

quantity

Number

The quantity for the line item to be set. If the line item is already in the cart, the quantity is added. Defaults to one.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/561dbfe0-2679-49ac-b388-e201ea1dbcd6/line-items/1eb53c01-922a-44dd-bb38-63070585bc6e' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '{"_type":"PRODUCT","_ref":"ab63b361-9dc2-4463-b84b-a5ce227a25a3","quantity":2}'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 6553

{
  "_id" : "561dbfe0-2679-49ac-b388-e201ea1dbcd6",
  "lineItems" : [ {
    "_type" : "PRODUCT",
    "_id" : "1eb53c01-922a-44dd-bb38-63070585bc6e",
    "_ref" : "ab63b361-9dc2-4463-b84b-a5ce227a25a3",
    "name" : "High Protein Power Bar (Pack of 5)",
    "quantity" : 2,
    "singleItemPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 4.95
    },
    "lineItemPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 9.9
    },
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 1.881
    },
    "_embedded" : {
      "product" : {
        "_id" : "ab63b361-9dc2-4463-b84b-a5ce227a25a3",
        "sku" : "EB001",
        "essentialFeatures" : "Preservative-free. No added sweeteners. Vegan.",
        "variationAttributeValues" : [ {
          "displayName" : "flavor",
          "value" : "Salted Caramel"
        } ],
        "_links" : {
          "product" : {
            "href" : "https://api-shop.beyondshop.cloud/api/product-view/products/ab63b361-9dc2-4463-b84b-a5ce227a25a3?locale=undefined-UNDEFINED"
          },
          "default-image-data" : {
            "href" : "https://api-shop.beyondshop.cloud/api/http:/your.image.hoster.com/randomimage.png"
          }
        }
      }
    },
    "_links" : {
      "self" : {
        "href" : "https://api-shop.beyondshop.cloud/api/carts/561dbfe0-2679-49ac-b388-e201ea1dbcd6/line-items/1eb53c01-922a-44dd-bb38-63070585bc6e"
      }
    }
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.0,
      "currency" : "EUR",
      "amount" : 0
    } ],
    "_embedded" : {
      "shipping-method" : {
        "_id" : "8090126c-4b44-4bbc-b812-7f2a243f46fe",
        "name" : "Standard",
        "description" : "Standard shipping. Delivery within 3-4 days.",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : null,
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 19.99
        },
        "weightBasedPrice" : null,
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/d1f51e59-0418-4a6b-bf3c-eba157f03a5d/shipping-methods/8090126c-4b44-4bbc-b812-7f2a243f46fe"
          }
        }
      }
    }
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.0,
      "currency" : "EUR",
      "amount" : 0
    } ],
    "_embedded" : {
      "payment-method" : {
        "_id" : "7196bce6-f189-47b2-acd7-47e543fca469",
        "name" : "Converge",
        "description" : "Pay by Converge.",
        "officialName" : "Converge",
        "officialDescription" : "Pay by Converge.",
        "taxClass" : "REGULAR",
        "discountOrFee" : {
          "type" : "ABSOLUTE",
          "absoluteValue" : {
            "taxModel" : "GROSS",
            "currency" : "EUR",
            "amount" : 2
          },
          "percentageValue" : null
        },
        "position" : 1,
        "serviceableCountries" : [ "DE" ],
        "minimumOrderValue" : null,
        "activated" : true,
        "activeLogoSet" : null,
        "onlinePayment" : false,
        "workflow" : null,
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/7196bce6-f189-47b2-acd7-47e543fca469"
          },
          "payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/7196bce6-f189-47b2-acd7-47e543fca469"
          },
          "deactivate-payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/7196bce6-f189-47b2-acd7-47e543fca469/deactivate"
          },
          "payment-method-definition" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/7196bce6-f189-47b2-acd7-47e543fca469/payment-method-definition"
          }
        }
      }
    }
  },
  "billingAddress" : null,
  "shippingAddress" : null,
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 9.9
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 31.89
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 31.89
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 31.89
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "taxes" : [ {
    "taxClass" : "REGULAR",
    "taxRate" : 0.0,
    "currency" : "EUR",
    "amount" : 0
  } ],
  "taxable" : true,
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 4
  },
  "mustAcceptTermsAndConditions" : false,
  "weight" : 380,
  "checkoutState" : {
    "shippingMethodValid" : true,
    "shippingMethodSelectable" : true,
    "paymentMethodValid" : true,
    "paymentMethodSelectable" : true,
    "billingAddressSet" : false,
    "priceValidToOrder" : true,
    "paymentTransactionStatus" : "NO_APPROVAL_NEEDED",
    "readyToOrder" : false
  },
  "customerEmail" : null,
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/561dbfe0-2679-49ac-b388-e201ea1dbcd6"
    },
    "line-items" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/561dbfe0-2679-49ac-b388-e201ea1dbcd6/line-items"
    },
    "shipping-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/561dbfe0-2679-49ac-b388-e201ea1dbcd6/shipping-methods"
    },
    "shipping-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/561dbfe0-2679-49ac-b388-e201ea1dbcd6/shipping-methods/default"
    },
    "shipping-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/561dbfe0-2679-49ac-b388-e201ea1dbcd6/shipping-methods/current"
    },
    "payment-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/561dbfe0-2679-49ac-b388-e201ea1dbcd6/payment-methods"
    },
    "payment-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/561dbfe0-2679-49ac-b388-e201ea1dbcd6/payment-methods/default"
    },
    "payment-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/561dbfe0-2679-49ac-b388-e201ea1dbcd6/payment-methods/current"
    },
    "billing-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/561dbfe0-2679-49ac-b388-e201ea1dbcd6/billing-address"
    },
    "shipping-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/561dbfe0-2679-49ac-b388-e201ea1dbcd6/shipping-address"
    }
  }
}

Replace line items

A PUT request is used to replace the current line items in the cart with the given list.

Request body properties

Path Type Description

[]

Array

The list of line items.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/ab0eef90-ff7f-43e1-a1ca-8ec52f93700a/line-items' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '[{"_type":"PRODUCT","_ref":"fd9ac7dd-fadb-4218-a51f-7a87abd041a6","quantity":1}]'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 6556

{
  "_id" : "ab0eef90-ff7f-43e1-a1ca-8ec52f93700a",
  "lineItems" : [ {
    "_type" : "PRODUCT",
    "_id" : "75f10437-ac49-44f8-9fc8-b71429eac66b",
    "_ref" : "fd9ac7dd-fadb-4218-a51f-7a87abd041a6",
    "name" : "High Protein Power Bar (Pack of 5)",
    "quantity" : 1,
    "singleItemPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 4.95
    },
    "lineItemPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 4.95
    },
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 0.9405
    },
    "_embedded" : {
      "product" : {
        "_id" : "fd9ac7dd-fadb-4218-a51f-7a87abd041a6",
        "sku" : "EB001",
        "essentialFeatures" : "Preservative-free. No added sweeteners. Vegan.",
        "variationAttributeValues" : [ {
          "displayName" : "flavor",
          "value" : "Salted Caramel"
        } ],
        "_links" : {
          "product" : {
            "href" : "https://api-shop.beyondshop.cloud/api/product-view/products/fd9ac7dd-fadb-4218-a51f-7a87abd041a6?locale=undefined-UNDEFINED"
          },
          "default-image-data" : {
            "href" : "https://api-shop.beyondshop.cloud/api/http:/your.image.hoster.com/randomimage.png"
          }
        }
      }
    },
    "_links" : {
      "self" : {
        "href" : "https://api-shop.beyondshop.cloud/api/carts/ab0eef90-ff7f-43e1-a1ca-8ec52f93700a/line-items/75f10437-ac49-44f8-9fc8-b71429eac66b"
      }
    }
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.0,
      "currency" : "EUR",
      "amount" : 0
    } ],
    "_embedded" : {
      "shipping-method" : {
        "_id" : "4ab7382e-811a-4fa6-8e1d-0919d391b4d4",
        "name" : "Standard",
        "description" : "Standard shipping. Delivery within 3-4 days.",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : null,
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 19.99
        },
        "weightBasedPrice" : null,
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/86a5ffcf-6f0a-4636-bfc3-d6a92c01de93/shipping-methods/4ab7382e-811a-4fa6-8e1d-0919d391b4d4"
          }
        }
      }
    }
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.0,
      "currency" : "EUR",
      "amount" : 0
    } ],
    "_embedded" : {
      "payment-method" : {
        "_id" : "cc49f461-2a85-48c2-aa33-2ff8807f77d8",
        "name" : "Converge",
        "description" : "Pay by Converge.",
        "officialName" : "Converge",
        "officialDescription" : "Pay by Converge.",
        "taxClass" : "REGULAR",
        "discountOrFee" : {
          "type" : "ABSOLUTE",
          "absoluteValue" : {
            "taxModel" : "GROSS",
            "currency" : "EUR",
            "amount" : 2
          },
          "percentageValue" : null
        },
        "position" : 1,
        "serviceableCountries" : [ "DE" ],
        "minimumOrderValue" : null,
        "activated" : true,
        "activeLogoSet" : null,
        "onlinePayment" : false,
        "workflow" : null,
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/cc49f461-2a85-48c2-aa33-2ff8807f77d8"
          },
          "payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/cc49f461-2a85-48c2-aa33-2ff8807f77d8"
          },
          "deactivate-payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/cc49f461-2a85-48c2-aa33-2ff8807f77d8/deactivate"
          },
          "payment-method-definition" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/cc49f461-2a85-48c2-aa33-2ff8807f77d8/payment-method-definition"
          }
        }
      }
    }
  },
  "billingAddress" : null,
  "shippingAddress" : null,
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 4.95
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 26.94
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 26.94
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 26.94
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "taxes" : [ {
    "taxClass" : "REGULAR",
    "taxRate" : 0.0,
    "currency" : "EUR",
    "amount" : 0
  } ],
  "taxable" : true,
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 4
  },
  "mustAcceptTermsAndConditions" : false,
  "weight" : 190,
  "checkoutState" : {
    "shippingMethodValid" : true,
    "shippingMethodSelectable" : true,
    "paymentMethodValid" : true,
    "paymentMethodSelectable" : true,
    "billingAddressSet" : false,
    "priceValidToOrder" : true,
    "paymentTransactionStatus" : "NO_APPROVAL_NEEDED",
    "readyToOrder" : false
  },
  "customerEmail" : null,
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/ab0eef90-ff7f-43e1-a1ca-8ec52f93700a"
    },
    "line-items" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/ab0eef90-ff7f-43e1-a1ca-8ec52f93700a/line-items"
    },
    "shipping-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/ab0eef90-ff7f-43e1-a1ca-8ec52f93700a/shipping-methods"
    },
    "shipping-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/ab0eef90-ff7f-43e1-a1ca-8ec52f93700a/shipping-methods/default"
    },
    "shipping-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/ab0eef90-ff7f-43e1-a1ca-8ec52f93700a/shipping-methods/current"
    },
    "payment-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/ab0eef90-ff7f-43e1-a1ca-8ec52f93700a/payment-methods"
    },
    "payment-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/ab0eef90-ff7f-43e1-a1ca-8ec52f93700a/payment-methods/default"
    },
    "payment-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/ab0eef90-ff7f-43e1-a1ca-8ec52f93700a/payment-methods/current"
    },
    "billing-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/ab0eef90-ff7f-43e1-a1ca-8ec52f93700a/billing-address"
    },
    "shipping-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/ab0eef90-ff7f-43e1-a1ca-8ec52f93700a/shipping-address"
    }
  }
}

Delete line item

A DELETE request is used to delete a line item from the cart.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/56cda025-f6e6-4de5-84b2-43f721168fbf/line-items/1d59714d-7a87-4fb0-9529-e0c1c311f4fa' -i -X DELETE

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 4825

{
  "_id" : "56cda025-f6e6-4de5-84b2-43f721168fbf",
  "lineItems" : [ ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "shipping-method" : {
        "_id" : "685abf31-0ffb-43fb-a9b1-7d5326459504",
        "name" : "Standard",
        "description" : "Standard shipping. Delivery within 3-4 days.",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : null,
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 19.99
        },
        "weightBasedPrice" : null,
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/aed453be-0628-40e1-9fd6-6ae0f6eacefb/shipping-methods/685abf31-0ffb-43fb-a9b1-7d5326459504"
          }
        }
      }
    }
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "payment-method" : {
        "_id" : "604955ef-6cc5-454b-b295-e76fac17922d",
        "name" : "Converge",
        "description" : "Pay by Converge.",
        "officialName" : "Converge",
        "officialDescription" : "Pay by Converge.",
        "taxClass" : "REGULAR",
        "discountOrFee" : {
          "type" : "ABSOLUTE",
          "absoluteValue" : {
            "taxModel" : "GROSS",
            "currency" : "EUR",
            "amount" : 2
          },
          "percentageValue" : null
        },
        "position" : 1,
        "serviceableCountries" : [ "DE" ],
        "minimumOrderValue" : null,
        "activated" : true,
        "activeLogoSet" : null,
        "onlinePayment" : false,
        "workflow" : null,
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/604955ef-6cc5-454b-b295-e76fac17922d"
          },
          "payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/604955ef-6cc5-454b-b295-e76fac17922d"
          },
          "deactivate-payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/604955ef-6cc5-454b-b295-e76fac17922d/deactivate"
          },
          "payment-method-definition" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/604955ef-6cc5-454b-b295-e76fac17922d/payment-method-definition"
          }
        }
      }
    }
  },
  "billingAddress" : null,
  "shippingAddress" : null,
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 21.99
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 21.99
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 21.99
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "taxes" : [ ],
  "taxable" : true,
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 4
  },
  "mustAcceptTermsAndConditions" : false,
  "weight" : 0,
  "checkoutState" : {
    "shippingMethodValid" : true,
    "shippingMethodSelectable" : true,
    "paymentMethodValid" : true,
    "paymentMethodSelectable" : true,
    "billingAddressSet" : false,
    "priceValidToOrder" : false,
    "paymentTransactionStatus" : "NO_APPROVAL_NEEDED",
    "readyToOrder" : false
  },
  "customerEmail" : null,
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/56cda025-f6e6-4de5-84b2-43f721168fbf"
    },
    "line-items" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/56cda025-f6e6-4de5-84b2-43f721168fbf/line-items"
    },
    "shipping-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/56cda025-f6e6-4de5-84b2-43f721168fbf/shipping-methods"
    },
    "shipping-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/56cda025-f6e6-4de5-84b2-43f721168fbf/shipping-methods/default"
    },
    "shipping-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/56cda025-f6e6-4de5-84b2-43f721168fbf/shipping-methods/current"
    },
    "payment-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/56cda025-f6e6-4de5-84b2-43f721168fbf/payment-methods"
    },
    "payment-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/56cda025-f6e6-4de5-84b2-43f721168fbf/payment-methods/default"
    },
    "payment-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/56cda025-f6e6-4de5-84b2-43f721168fbf/payment-methods/current"
    },
    "billing-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/56cda025-f6e6-4de5-84b2-43f721168fbf/billing-address"
    },
    "shipping-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/56cda025-f6e6-4de5-84b2-43f721168fbf/shipping-address"
    }
  }
}

The cart address resources handle the billing and shipping address of a cart.

Set cart billing address

A PUT request is used to set the billing address of the cart. The billing address is mandatory for a cart being ready to order.

Request body properties

Path Type Description Constraints

salutation

String

The customer’s salutation, e.g. Mr or Mrs.

Length must be between 0 and 30 inclusive

gender

String

The customer’s grammatical gender. Can be FEMALE, MALE, or UNDEFINED.

title

String

The customer’s academic title, e.g. professor, or PhD.

Length must be between 0 and 100 inclusive

firstName

String

The first name of the customer.

Length must be between 0 and 50 inclusive

middleName

String

The middle name of the customer.

Length must be between 0 and 100 inclusive

lastName

String

The last name of the customer.

Length must be between 0 and 50 inclusive

street

String

The street of the customer address.

Length must be between 0 and 200 inclusive. Must not be empty

houseNumber

String

The house number of the customer address.

Length must be between 0 and 20 inclusive

street2

String

Additional street field of the customer address.

Length must be between 0 and 200 inclusive

doorCode

String

The door code of the customer address.

addressExtension

String

The address extension of the customer address, e.g. PO box.

Length must be between 0 and 200 inclusive

postalCode

String

The zip code of the customer address.

Length must be between 0 and 25 inclusive

dependentLocality

String

Additional locality information such as a village or suburb name, giving a more specific location.

Length must be between 0 and 60 inclusive

city

String

The city of the customer address.

Length must be between 0 and 60 inclusive. Must not be empty

country

String

A two letter country code according to ISO 3166-1. Only officially assigned country codes.

Must be an officially assigned country code (see ISO 3166-1 Alpha-2). Must not be null. The address country must be in the list of shipping countries of the shop

state

String

The state of the customer address.

Length must be between 0 and 100 inclusive

email

String

The email address of the customer.

Length must be between 0 and 150 inclusive. Must be a well-formed email address. Must not be empty

phone

String

The landline phone number of the customer.

Length must be between 0 and 40 inclusive

mobile

String

The mobile phone number of the customer.

Length must be between 0 and 40 inclusive

vatId

String

Length must be between 0 and 20 inclusive

taxNumber

String

Length must be between 0 and 50 inclusive

birthDate

String

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/1f96d5b4-a0f2-45d1-b508-3ae430f6eaaf/billing-address' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -d '{"salutation":"Mrs","gender":"FEMALE","title":"","firstName":"Astrid","middleName":"Agnes","lastName":"Alster","street":"Alsterwasserweg","houseNumber":"2","street2":"Erdgeschoss","doorCode":"0185","addressExtension":"Hinterhof","postalCode":"20999","dependentLocality":"Seevetal","city":"Alsterwasser","country":"DE","state":"Hamburg","email":"a.alsterh@example.com","phone":"(800) 555-0102","mobile":"(800) 555-0103","vatId":"123456789","taxNumber":"123-34-6789","birthDate":"1985-03-20"}'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 5617

{
  "_id" : "1f96d5b4-a0f2-45d1-b508-3ae430f6eaaf",
  "lineItems" : [ ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "shipping-method" : {
        "_id" : "3c9887ac-3968-40d2-91ec-74dba32e7dc5",
        "name" : "Standard",
        "description" : "Standard shipping. Delivery within 3-4 days.",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : null,
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 19.99
        },
        "weightBasedPrice" : null,
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/5290a75b-9591-4f59-a252-ee5f2e4a1c76/shipping-methods/3c9887ac-3968-40d2-91ec-74dba32e7dc5"
          }
        }
      }
    }
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "payment-method" : {
        "_id" : "35b88228-9142-4f63-93fe-6e3bf255902d",
        "name" : "Converge",
        "description" : "Pay by Converge.",
        "officialName" : "Converge",
        "officialDescription" : "Pay by Converge.",
        "taxClass" : "REGULAR",
        "discountOrFee" : {
          "type" : "ABSOLUTE",
          "absoluteValue" : {
            "taxModel" : "GROSS",
            "currency" : "EUR",
            "amount" : 2
          },
          "percentageValue" : null
        },
        "position" : 1,
        "serviceableCountries" : [ "DE" ],
        "minimumOrderValue" : null,
        "activated" : true,
        "activeLogoSet" : null,
        "onlinePayment" : false,
        "workflow" : null,
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/35b88228-9142-4f63-93fe-6e3bf255902d"
          },
          "payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/35b88228-9142-4f63-93fe-6e3bf255902d"
          },
          "deactivate-payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/35b88228-9142-4f63-93fe-6e3bf255902d/deactivate"
          },
          "payment-method-definition" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/35b88228-9142-4f63-93fe-6e3bf255902d/payment-method-definition"
          }
        }
      }
    }
  },
  "billingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : null,
    "title" : "",
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "Erdgeschoss",
    "addressExtension" : "Hinterhof",
    "postalCode" : "20999",
    "dependentLocality" : "Seevetal",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a.alsterh@example.com",
    "phone" : "(800) 555-0102",
    "mobile" : "(800) 555-0103",
    "displayAddressLines" : [ "Astrid Agnes Alster", "Alsterwasserweg 2", "Erdgeschoss", "Hinterhof", "Seevetal", "20999 Alsterwasser", "DEUTSCHLAND" ],
    "vatId" : "123456789",
    "taxNumber" : "123-34-6789",
    "birthDate" : "1985-03-20"
  },
  "shippingAddress" : null,
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 21.99
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 21.99
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 21.99
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "taxes" : [ ],
  "taxable" : true,
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 4
  },
  "mustAcceptTermsAndConditions" : false,
  "weight" : 0,
  "checkoutState" : {
    "shippingMethodValid" : true,
    "shippingMethodSelectable" : true,
    "paymentMethodValid" : true,
    "paymentMethodSelectable" : true,
    "billingAddressSet" : true,
    "priceValidToOrder" : false,
    "paymentTransactionStatus" : "NO_APPROVAL_NEEDED",
    "readyToOrder" : false
  },
  "customerEmail" : null,
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/1f96d5b4-a0f2-45d1-b508-3ae430f6eaaf"
    },
    "line-items" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/1f96d5b4-a0f2-45d1-b508-3ae430f6eaaf/line-items"
    },
    "shipping-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/1f96d5b4-a0f2-45d1-b508-3ae430f6eaaf/shipping-methods"
    },
    "shipping-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/1f96d5b4-a0f2-45d1-b508-3ae430f6eaaf/shipping-methods/default"
    },
    "shipping-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/1f96d5b4-a0f2-45d1-b508-3ae430f6eaaf/shipping-methods/current"
    },
    "payment-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/1f96d5b4-a0f2-45d1-b508-3ae430f6eaaf/payment-methods"
    },
    "payment-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/1f96d5b4-a0f2-45d1-b508-3ae430f6eaaf/payment-methods/default"
    },
    "payment-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/1f96d5b4-a0f2-45d1-b508-3ae430f6eaaf/payment-methods/current"
    },
    "billing-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/1f96d5b4-a0f2-45d1-b508-3ae430f6eaaf/billing-address"
    },
    "shipping-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/1f96d5b4-a0f2-45d1-b508-3ae430f6eaaf/shipping-address"
    }
  }
}

Set cart shipping address

A PUT request is used to set the shipping address of the cart. If a shipping address is not set, it will default to the billing address.

Request body properties

Path Type Description Constraints

salutation

String

The customer’s salutation, e.g. Mr or Mrs.

Length must be between 0 and 30 inclusive

gender

String

The customer’s grammatical gender. Can be FEMALE, MALE, or UNDEFINED.

title

String

The customer’s academic title, e.g. professor, or PhD.

Length must be between 0 and 100 inclusive

firstName

String

The first name of the customer.

Length must be between 0 and 50 inclusive

middleName

String

The middle name of the customer.

Length must be between 0 and 100 inclusive

lastName

String

The last name of the customer.

Length must be between 0 and 50 inclusive

street

String

The street of the customer address.

Length must be between 0 and 200 inclusive. Must not be empty

houseNumber

String

The house number of the customer address.

Length must be between 0 and 20 inclusive

street2

String

Additional street field of the customer address.

Length must be between 0 and 200 inclusive

doorCode

String

The door code of the customer address.

addressExtension

String

The address extension of the customer address, e.g. PO box.

Length must be between 0 and 200 inclusive

postalCode

String

The zip code of the customer address.

Length must be between 0 and 25 inclusive

dependentLocality

String

Additional locality information such as a village or suburb name, giving a more specific location.

Length must be between 0 and 60 inclusive

city

String

The city of the customer address.

Length must be between 0 and 60 inclusive. Must not be empty

country

String

A two letter country code according to ISO 3166-1. Only officially assigned country codes.

Must be an officially assigned country code (see ISO 3166-1 Alpha-2). Must not be null. The address country must be in the list of shipping countries of the shop

state

String

The state of the customer address.

Length must be between 0 and 100 inclusive

email

String

The email address of the customer.

Length must be between 0 and 150 inclusive. Must be a well-formed email address. Must not be empty

phone

String

The landline phone number of the customer.

Length must be between 0 and 40 inclusive

mobile

String

The mobile phone number of the customer.

Length must be between 0 and 40 inclusive

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/e4c401d9-c6cd-4eff-93da-ae39d1537e11/shipping-address' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -d '{"salutation":"Mrs","gender":"FEMALE","title":"","firstName":"Astrid","middleName":"Agnes","lastName":"Alster","street":"Alsterwasserweg","houseNumber":"2","street2":"Erdgeschoss","doorCode":"0185","addressExtension":"Hinterhof","postalCode":"20999","dependentLocality":"Seevetal","city":"Alsterwasser","country":"DE","state":"Hamburg","email":"a.alsterh@example.com","phone":"(800) 555-0102","mobile":"(800) 555-0103"}'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 5551

{
  "_id" : "e4c401d9-c6cd-4eff-93da-ae39d1537e11",
  "lineItems" : [ ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "shipping-method" : {
        "_id" : "e929ed20-667e-43cf-99e1-cb405bf51744",
        "name" : "Standard",
        "description" : "Standard shipping. Delivery within 3-4 days.",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : null,
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 19.99
        },
        "weightBasedPrice" : null,
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/99f180ab-f8db-46c3-8bcd-ce728e6991f2/shipping-methods/e929ed20-667e-43cf-99e1-cb405bf51744"
          }
        }
      }
    }
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "payment-method" : {
        "_id" : "f62bb8db-f2be-4c98-9cf4-49c786a38a95",
        "name" : "Converge",
        "description" : "Pay by Converge.",
        "officialName" : "Converge",
        "officialDescription" : "Pay by Converge.",
        "taxClass" : "REGULAR",
        "discountOrFee" : {
          "type" : "ABSOLUTE",
          "absoluteValue" : {
            "taxModel" : "GROSS",
            "currency" : "EUR",
            "amount" : 2
          },
          "percentageValue" : null
        },
        "position" : 1,
        "serviceableCountries" : [ "DE" ],
        "minimumOrderValue" : null,
        "activated" : true,
        "activeLogoSet" : null,
        "onlinePayment" : false,
        "workflow" : null,
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/f62bb8db-f2be-4c98-9cf4-49c786a38a95"
          },
          "payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/f62bb8db-f2be-4c98-9cf4-49c786a38a95"
          },
          "deactivate-payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/f62bb8db-f2be-4c98-9cf4-49c786a38a95/deactivate"
          },
          "payment-method-definition" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/f62bb8db-f2be-4c98-9cf4-49c786a38a95/payment-method-definition"
          }
        }
      }
    }
  },
  "billingAddress" : null,
  "shippingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : null,
    "title" : "",
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "Erdgeschoss",
    "addressExtension" : "Hinterhof",
    "postalCode" : "20999",
    "dependentLocality" : "Seevetal",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a.alsterh@example.com",
    "phone" : "(800) 555-0102",
    "mobile" : "(800) 555-0103",
    "displayAddressLines" : [ "Astrid Agnes Alster", "Alsterwasserweg 2", "Erdgeschoss", "Hinterhof", "Seevetal", "20999 Alsterwasser", "DEUTSCHLAND" ],
    "doorCode" : "0185"
  },
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 21.99
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 21.99
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 21.99
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "taxes" : [ ],
  "taxable" : true,
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 4
  },
  "mustAcceptTermsAndConditions" : false,
  "weight" : 0,
  "checkoutState" : {
    "shippingMethodValid" : true,
    "shippingMethodSelectable" : true,
    "paymentMethodValid" : true,
    "paymentMethodSelectable" : true,
    "billingAddressSet" : false,
    "priceValidToOrder" : false,
    "paymentTransactionStatus" : "NO_APPROVAL_NEEDED",
    "readyToOrder" : false
  },
  "customerEmail" : null,
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/e4c401d9-c6cd-4eff-93da-ae39d1537e11"
    },
    "line-items" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/e4c401d9-c6cd-4eff-93da-ae39d1537e11/line-items"
    },
    "shipping-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/e4c401d9-c6cd-4eff-93da-ae39d1537e11/shipping-methods"
    },
    "shipping-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/e4c401d9-c6cd-4eff-93da-ae39d1537e11/shipping-methods/default"
    },
    "shipping-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/e4c401d9-c6cd-4eff-93da-ae39d1537e11/shipping-methods/current"
    },
    "payment-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/e4c401d9-c6cd-4eff-93da-ae39d1537e11/payment-methods"
    },
    "payment-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/e4c401d9-c6cd-4eff-93da-ae39d1537e11/payment-methods/default"
    },
    "payment-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/e4c401d9-c6cd-4eff-93da-ae39d1537e11/payment-methods/current"
    },
    "billing-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/e4c401d9-c6cd-4eff-93da-ae39d1537e11/billing-address"
    },
    "shipping-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/e4c401d9-c6cd-4eff-93da-ae39d1537e11/shipping-address"
    }
  }
}

Remove cart shipping address

A DELETE request is used to remove the shipping address of the cart. After deletion, the shipping address will default to the billing address.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/6c1b13ea-3b1f-4d74-9d24-8695f51fa52a/shipping-address' -i -X DELETE \
    -H 'Accept: application/hal+json'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 4825

{
  "_id" : "6c1b13ea-3b1f-4d74-9d24-8695f51fa52a",
  "lineItems" : [ ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "shipping-method" : {
        "_id" : "46ebcf7c-8fef-409b-89c0-b5155cdd6fe4",
        "name" : "Standard",
        "description" : "Standard shipping. Delivery within 3-4 days.",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : null,
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 19.99
        },
        "weightBasedPrice" : null,
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/4159f4be-f1c8-47e9-ace9-3a5c3c6fb4c4/shipping-methods/46ebcf7c-8fef-409b-89c0-b5155cdd6fe4"
          }
        }
      }
    }
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "payment-method" : {
        "_id" : "0164d082-132d-4231-8695-35052dba6d91",
        "name" : "Converge",
        "description" : "Pay by Converge.",
        "officialName" : "Converge",
        "officialDescription" : "Pay by Converge.",
        "taxClass" : "REGULAR",
        "discountOrFee" : {
          "type" : "ABSOLUTE",
          "absoluteValue" : {
            "taxModel" : "GROSS",
            "currency" : "EUR",
            "amount" : 2
          },
          "percentageValue" : null
        },
        "position" : 1,
        "serviceableCountries" : [ "DE" ],
        "minimumOrderValue" : null,
        "activated" : true,
        "activeLogoSet" : null,
        "onlinePayment" : false,
        "workflow" : null,
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/0164d082-132d-4231-8695-35052dba6d91"
          },
          "payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/0164d082-132d-4231-8695-35052dba6d91"
          },
          "deactivate-payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/0164d082-132d-4231-8695-35052dba6d91/deactivate"
          },
          "payment-method-definition" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/0164d082-132d-4231-8695-35052dba6d91/payment-method-definition"
          }
        }
      }
    }
  },
  "billingAddress" : null,
  "shippingAddress" : null,
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 21.99
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 21.99
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 21.99
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "taxes" : [ ],
  "taxable" : true,
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 4
  },
  "mustAcceptTermsAndConditions" : false,
  "weight" : 0,
  "checkoutState" : {
    "shippingMethodValid" : true,
    "shippingMethodSelectable" : true,
    "paymentMethodValid" : true,
    "paymentMethodSelectable" : true,
    "billingAddressSet" : false,
    "priceValidToOrder" : false,
    "paymentTransactionStatus" : "NO_APPROVAL_NEEDED",
    "readyToOrder" : false
  },
  "customerEmail" : null,
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/6c1b13ea-3b1f-4d74-9d24-8695f51fa52a"
    },
    "line-items" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/6c1b13ea-3b1f-4d74-9d24-8695f51fa52a/line-items"
    },
    "shipping-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/6c1b13ea-3b1f-4d74-9d24-8695f51fa52a/shipping-methods"
    },
    "shipping-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/6c1b13ea-3b1f-4d74-9d24-8695f51fa52a/shipping-methods/default"
    },
    "shipping-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/6c1b13ea-3b1f-4d74-9d24-8695f51fa52a/shipping-methods/current"
    },
    "payment-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/6c1b13ea-3b1f-4d74-9d24-8695f51fa52a/payment-methods"
    },
    "payment-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/6c1b13ea-3b1f-4d74-9d24-8695f51fa52a/payment-methods/default"
    },
    "payment-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/6c1b13ea-3b1f-4d74-9d24-8695f51fa52a/payment-methods/current"
    },
    "billing-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/6c1b13ea-3b1f-4d74-9d24-8695f51fa52a/billing-address"
    },
    "shipping-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/6c1b13ea-3b1f-4d74-9d24-8695f51fa52a/shipping-address"
    }
  }
}

The cart payment method resources hold information on the payment methods handled for a cart.

Set current cart payment method

A PUT request is used to set the current payment method of the cart.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/b422bdda-eaec-4703-98f5-d9d02bd0c35a/payment-methods/current' -i -X PUT \
    -H 'Content-Type: text/uri-list' \
    -H 'Accept: application/json' \
    -d 'https://api-shop.beyondshop.cloud/api/payment-methods/e514da1c-113c-46a7-91cf-a6f59fe42187'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 6547

{
  "_id" : "b422bdda-eaec-4703-98f5-d9d02bd0c35a",
  "lineItems" : [ {
    "_type" : "PRODUCT",
    "_id" : "b1da95ab-ebeb-4d0e-b854-089a77e79f73",
    "_ref" : "000b750e-8637-4d12-99c4-f67cc0210857",
    "name" : "High Protein Power Bar (Pack of 5)",
    "quantity" : 1,
    "singleItemPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 4.95
    },
    "lineItemPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 4.95
    },
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 0.9405
    },
    "_embedded" : {
      "product" : {
        "_id" : "000b750e-8637-4d12-99c4-f67cc0210857",
        "sku" : "EB001",
        "essentialFeatures" : "Preservative-free. No added sweeteners. Vegan.",
        "variationAttributeValues" : [ {
          "displayName" : "flavor",
          "value" : "Salted Caramel"
        } ],
        "_links" : {
          "product" : {
            "href" : "https://api-shop.beyondshop.cloud/api/product-view/products/000b750e-8637-4d12-99c4-f67cc0210857?locale=undefined-UNDEFINED"
          },
          "default-image-data" : {
            "href" : "https://api-shop.beyondshop.cloud/api/http:/your.image.hoster.com/randomimage.png"
          }
        }
      }
    },
    "_links" : {
      "self" : {
        "href" : "https://api-shop.beyondshop.cloud/api/carts/b422bdda-eaec-4703-98f5-d9d02bd0c35a/line-items/b1da95ab-ebeb-4d0e-b854-089a77e79f73"
      }
    }
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.0,
      "currency" : "EUR",
      "amount" : 0
    } ],
    "_embedded" : {
      "shipping-method" : {
        "_id" : "dbf6b33d-352a-4334-99fa-1a02c3a4debb",
        "name" : "Standard",
        "description" : "Standard shipping. Delivery within 3-4 days.",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : null,
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 19.99
        },
        "weightBasedPrice" : null,
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/4e771241-ee69-4812-aa87-f4bc308cb13e/shipping-methods/dbf6b33d-352a-4334-99fa-1a02c3a4debb"
          }
        }
      }
    }
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 0.4988
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.0,
      "currency" : "EUR",
      "amount" : 0
    } ],
    "_embedded" : {
      "payment-method" : {
        "_id" : "e514da1c-113c-46a7-91cf-a6f59fe42187",
        "name" : "Credit card",
        "description" : "Pay by credit card.",
        "officialName" : "Credit card",
        "officialDescription" : "Pay by credit card.",
        "taxClass" : "REGULAR",
        "discountOrFee" : {
          "type" : "PERCENTAGE",
          "absoluteValue" : null,
          "percentageValue" : 0.02
        },
        "position" : 2,
        "serviceableCountries" : [ "DE", "GB" ],
        "minimumOrderValue" : {
          "currency" : "EUR",
          "amount" : 20
        },
        "activated" : true,
        "activeLogoSet" : null,
        "onlinePayment" : false,
        "workflow" : null,
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/e514da1c-113c-46a7-91cf-a6f59fe42187"
          },
          "payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/e514da1c-113c-46a7-91cf-a6f59fe42187"
          },
          "deactivate-payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/e514da1c-113c-46a7-91cf-a6f59fe42187/deactivate"
          },
          "payment-method-definition" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/e514da1c-113c-46a7-91cf-a6f59fe42187/payment-method-definition"
          }
        }
      }
    }
  },
  "billingAddress" : null,
  "shippingAddress" : null,
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 4.95
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 25.4388
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 25.4388
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 25.4388
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "taxes" : [ {
    "taxClass" : "REGULAR",
    "taxRate" : 0.0,
    "currency" : "EUR",
    "amount" : 0
  } ],
  "taxable" : true,
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 4
  },
  "mustAcceptTermsAndConditions" : false,
  "weight" : 190,
  "checkoutState" : {
    "shippingMethodValid" : true,
    "shippingMethodSelectable" : true,
    "paymentMethodValid" : true,
    "paymentMethodSelectable" : false,
    "billingAddressSet" : false,
    "priceValidToOrder" : true,
    "paymentTransactionStatus" : "NO_APPROVAL_NEEDED",
    "readyToOrder" : false
  },
  "customerEmail" : null,
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/b422bdda-eaec-4703-98f5-d9d02bd0c35a"
    },
    "line-items" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/b422bdda-eaec-4703-98f5-d9d02bd0c35a/line-items"
    },
    "shipping-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/b422bdda-eaec-4703-98f5-d9d02bd0c35a/shipping-methods"
    },
    "shipping-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/b422bdda-eaec-4703-98f5-d9d02bd0c35a/shipping-methods/default"
    },
    "shipping-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/b422bdda-eaec-4703-98f5-d9d02bd0c35a/shipping-methods/current"
    },
    "payment-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/b422bdda-eaec-4703-98f5-d9d02bd0c35a/payment-methods"
    },
    "payment-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/b422bdda-eaec-4703-98f5-d9d02bd0c35a/payment-methods/default"
    },
    "payment-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/b422bdda-eaec-4703-98f5-d9d02bd0c35a/payment-methods/current"
    },
    "billing-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/b422bdda-eaec-4703-98f5-d9d02bd0c35a/billing-address"
    },
    "shipping-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/b422bdda-eaec-4703-98f5-d9d02bd0c35a/shipping-address"
    }
  }
}

Set cart payment method to current default

A PUT request is used to set the payment method to the current default payment method. The default payment method is the one with the highest priority of the applicable payment methods.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/9427ef88-d435-4caf-bccd-814c8e4a98f5/payment-methods/default' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 4825

{
  "_id" : "9427ef88-d435-4caf-bccd-814c8e4a98f5",
  "lineItems" : [ ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "shipping-method" : {
        "_id" : "f765a629-c72f-403f-ada3-ee1d293af292",
        "name" : "Standard",
        "description" : "Standard shipping. Delivery within 3-4 days.",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : null,
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 19.99
        },
        "weightBasedPrice" : null,
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/c6a02bf2-76f1-4f85-80c5-aa49604487b4/shipping-methods/f765a629-c72f-403f-ada3-ee1d293af292"
          }
        }
      }
    }
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "payment-method" : {
        "_id" : "b3ae3269-4ec8-4e42-9844-7f43a5c72801",
        "name" : "Converge",
        "description" : "Pay by Converge.",
        "officialName" : "Converge",
        "officialDescription" : "Pay by Converge.",
        "taxClass" : "REGULAR",
        "discountOrFee" : {
          "type" : "ABSOLUTE",
          "absoluteValue" : {
            "taxModel" : "GROSS",
            "currency" : "EUR",
            "amount" : 2
          },
          "percentageValue" : null
        },
        "position" : 1,
        "serviceableCountries" : [ "DE" ],
        "minimumOrderValue" : null,
        "activated" : true,
        "activeLogoSet" : null,
        "onlinePayment" : false,
        "workflow" : null,
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/b3ae3269-4ec8-4e42-9844-7f43a5c72801"
          },
          "payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/b3ae3269-4ec8-4e42-9844-7f43a5c72801"
          },
          "deactivate-payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/b3ae3269-4ec8-4e42-9844-7f43a5c72801/deactivate"
          },
          "payment-method-definition" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/b3ae3269-4ec8-4e42-9844-7f43a5c72801/payment-method-definition"
          }
        }
      }
    }
  },
  "billingAddress" : null,
  "shippingAddress" : null,
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 21.99
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 21.99
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 21.99
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "taxes" : [ ],
  "taxable" : true,
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 4
  },
  "mustAcceptTermsAndConditions" : false,
  "weight" : 0,
  "checkoutState" : {
    "shippingMethodValid" : true,
    "shippingMethodSelectable" : true,
    "paymentMethodValid" : true,
    "paymentMethodSelectable" : true,
    "billingAddressSet" : false,
    "priceValidToOrder" : false,
    "paymentTransactionStatus" : "NO_APPROVAL_NEEDED",
    "readyToOrder" : false
  },
  "customerEmail" : null,
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9427ef88-d435-4caf-bccd-814c8e4a98f5"
    },
    "line-items" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9427ef88-d435-4caf-bccd-814c8e4a98f5/line-items"
    },
    "shipping-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9427ef88-d435-4caf-bccd-814c8e4a98f5/shipping-methods"
    },
    "shipping-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9427ef88-d435-4caf-bccd-814c8e4a98f5/shipping-methods/default"
    },
    "shipping-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9427ef88-d435-4caf-bccd-814c8e4a98f5/shipping-methods/current"
    },
    "payment-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9427ef88-d435-4caf-bccd-814c8e4a98f5/payment-methods"
    },
    "payment-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9427ef88-d435-4caf-bccd-814c8e4a98f5/payment-methods/default"
    },
    "payment-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9427ef88-d435-4caf-bccd-814c8e4a98f5/payment-methods/current"
    },
    "billing-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9427ef88-d435-4caf-bccd-814c8e4a98f5/billing-address"
    },
    "shipping-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9427ef88-d435-4caf-bccd-814c8e4a98f5/shipping-address"
    }
  }
}

Show current cart payment method details

A GET request is used to get the current payment method. The payment method type is documented here.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/6532e7cb-c432-4d41-9057-6f0ad8655e5a/payment-methods/current' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1158

{
  "_id" : "42c311e8-6ec4-4313-b43c-05b4347b3926",
  "name" : "Converge",
  "description" : "Pay by Converge.",
  "officialName" : "Converge",
  "officialDescription" : "Pay by Converge.",
  "taxClass" : "REGULAR",
  "discountOrFee" : {
    "type" : "ABSOLUTE",
    "absoluteValue" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2
    },
    "percentageValue" : null
  },
  "position" : 1,
  "serviceableCountries" : [ "DE" ],
  "minimumOrderValue" : null,
  "activated" : true,
  "activeLogoSet" : null,
  "onlinePayment" : false,
  "workflow" : null,
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/42c311e8-6ec4-4313-b43c-05b4347b3926"
    },
    "payment-method" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/42c311e8-6ec4-4313-b43c-05b4347b3926"
    },
    "deactivate-payment-method" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/42c311e8-6ec4-4313-b43c-05b4347b3926/deactivate"
    },
    "payment-method-definition" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/42c311e8-6ec4-4313-b43c-05b4347b3926/payment-method-definition"
    }
  }
}

Show applicable cart payment method details

A GET request is used to get the applicable payment methods of a cart. The payment method type is documented here.

The selectable field indicates if a payment method is currently selectable. Non-selectable payment methods are currently restricted because of rules that apply to a cart. Trying to set such a payment method as the current one of the cart will fail.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/89011961-0855-4bae-ba7f-49bf1ec62d9b/payment-methods' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json'

Response body properties

Path Type Description

_embedded.payment-methods[].selectable

Boolean

Indicates if the payment method can be selected for the current cart. A payment method can be become non-selectable if the cart is modified, so that the minimumOrderValue is no longer reached. A cart with an non-selectable payment method cannot be ordered.

_embedded.payment-methods[].lineItemPrice

Object

The calculated price for this payment on the current cart.

_embedded.payment-methods[]._embedded.payment-method._id

String

The immutable, unique identifier of the requested resource.

_embedded.payment-methods[]._embedded.payment-method.position

Number

The sorting position of the payment method in the merchant’s cockpit in relation to other payment methods.

_embedded.payment-methods[]._embedded.payment-method.officialName

String

The official name of the payment method chosen by the merchant during setup.

_embedded.payment-methods[]._embedded.payment-method.officialDescription

String

The official description of the payment method chosen by the merchant during setup.

_embedded.payment-methods[]._embedded.payment-method.name

String

The name of the payment method that is used during checkout.

_embedded.payment-methods[]._embedded.payment-method.description

String

Description of the payment method that is used during checkout.

_embedded.payment-methods[]._embedded.payment-method.activated

Boolean

Indicates if a payment method is active. Can be true or false.

_embedded.payment-methods[]._embedded.payment-method.taxClass

String

The tax class. Can be REGULAR, REDUCED, or EXEMPT.

_embedded.payment-methods[]._embedded.payment-method.discountOrFee

Object

The details about the fee to be payed or discount to be granted for this payment method.

_embedded.payment-methods[]._embedded.payment-method.discountOrFee.type

String

The discount or fee can be an absolute or a percentage based value. Can be one of PERCENTAGE or ABSOLUTE. ABSOLUTE contains another attribute absoluteValue with a positive or negative price. PERCENTAGE contains another attribute percentageValue with a negative or positive percentage value.

_embedded.payment-methods[]._embedded.payment-method.serviceableCountries

Array

The list of target countries this payment method can be used in.

_embedded.payment-methods[]._embedded.payment-method.minimumOrderValue

Null

The minimum value of the cart so that this payment method can be used.

_embedded.payment-methods[]._embedded.payment-method.onlinePayment

Boolean

Indicates if the payment method is an online payment. Can be true or false.

_embedded.payment-methods[]._embedded.payment-method.activeLogoSet

Null

The name of the currently selected logo set. Can be TILE, DETAILS, LIST, or STOREFRONT. (official is always the fallback).

_embedded.payment-methods[]._embedded.payment-method.workflow

Null

The payment workflow for the current payment. Can be one of PAYMENT_ON_SELECTION, EMBEDDED_ON_SELECTION, PAYMENT_ON_BUY, or EMBEDDED_ON_BUY.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1856

{
  "_embedded" : {
    "payment-methods" : [ {
      "lineItemPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 2
      },
      "selectable" : true,
      "_embedded" : {
        "payment-method" : {
          "_id" : "e25b253d-a838-4560-959c-ed6a111f337f",
          "name" : "Converge",
          "description" : "Pay by Converge.",
          "officialName" : "Converge",
          "officialDescription" : "Pay by Converge.",
          "taxClass" : "REGULAR",
          "discountOrFee" : {
            "type" : "ABSOLUTE",
            "absoluteValue" : {
              "taxModel" : "GROSS",
              "currency" : "EUR",
              "amount" : 2
            },
            "percentageValue" : null
          },
          "position" : 1,
          "serviceableCountries" : [ "DE" ],
          "minimumOrderValue" : null,
          "activated" : true,
          "activeLogoSet" : null,
          "onlinePayment" : false,
          "workflow" : null,
          "_links" : {
            "self" : {
              "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/e25b253d-a838-4560-959c-ed6a111f337f"
            },
            "payment-method" : {
              "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/e25b253d-a838-4560-959c-ed6a111f337f"
            },
            "deactivate-payment-method" : {
              "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/e25b253d-a838-4560-959c-ed6a111f337f/deactivate"
            },
            "payment-method-definition" : {
              "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/e25b253d-a838-4560-959c-ed6a111f337f/payment-method-definition"
            }
          }
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/89011961-0855-4bae-ba7f-49bf1ec62d9b/payment-methods"
    }
  }
}

Create payment

A POST request is used to initiate the creation of a payment.

Request body properties

Path Type Description

returnUri

String

The redirect URI after successful payment authorization.

cancelUri

String

The URI to which the customer will be redirected if the customer canceled the payment or an error occurred.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/e30ec84a-4411-4d99-8b5e-6aaf31e8bac9/create-payment' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -d '{
  "returnUri" : "https://example.com/return",
  "cancelUri" : "https://example.com/cancel"
}'

Response body properties

Path Type Description

approvalUri

String

The URI used to approve the payment (optional). If present, the client has to redirect to this URI to initiate the approval.

embeddedApprovalUri

String

The optional URI to the iframe that will be embedded in the checkout UI.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 84

{
  "approvalUri" : "https://example.com/approval",
  "embeddedApprovalUri" : null
}

Create payment and order

Initiates payment and order for the cart identified by {cartId} with a single POST request.

Request body properties

Path Type Description

returnUri

String

The redirect URI after successful payment authorization.

cancelUri

String

The URI to which the customer will be redirected if the customer canceled the payment or an error occurred.

customerComment

String

An optional comment from the customer regarding the order.

salesChannel

String

The sales channel for this order, such as an online shop, point of sale, or a retail store. Defaults to {{default}}.

marketingChannel

String

The marketing channel for this order, such as a newsletter campaign, Google Shopping, or a Buy Button that’s implemented on a blog.

marketingSubchannel

String

The marketing subchannel for this order, such as a specific newsletter of a newsletter campaign, e.g. a Summer Sale that’s promoted on a blog, or a Winter Special that’s promoted on Facebook.

testOrder

Boolean

Indicates if this order is a test order. Can be true or false.

termsAndConditionsExplicitlyAccepted

Boolean

Indicates if the shop’s terms and conditions have been explicitly accepted. If explicit consent is required (see checkout settings) and not given, trying to order the cart will fail. Can be true or false.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/d667d684-f015-4a69-8e49-45dfc54e4aca/create-payment-and-order' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -d '{
  "returnUri" : "https://example.com/return",
  "cancelUri" : "https://example.com/cancel",
  "customerComment" : "Please send with UPS.",
  "salesChannel" : "Retail store",
  "marketingChannel" : "Google Shopping",
  "marketingSubchannel" : "Summer Sale",
  "testOrder" : false,
  "termsAndConditionsExplicitlyAccepted" : false
}'

Response body properties

Path Type Description

approvalUri

String

The URI used to approve the payment (optional). If present, the client has to redirect to this URI to initiate the approval.

embeddedApprovalUri

String

The optional URI to the iframe that will be embedded in the checkout UI.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 84

{
  "approvalUri" : "https://example.com/approval",
  "embeddedApprovalUri" : null
}

Categories

The categories resource is used to manage the categories of a shop. In the merchant’s cockpit a category is referred to as "collection".

Categories can be used to organize products into hierarchical structures and to classify them in different ways, e.g. for shop navigation. Products can appear in any number of categories, and there can be multiple category hierarchies for different purposes or channels. Categories are embedded in the product search so that products can be filtered according to their assignment.

List categories

A GET request will list all available categories in a paged manner.

Required scopes

catg:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/categories' -i -X GET \
    -H 'Content-Type: application/hal+json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_links

Object

See Hypermedia

page

Object

See Pagination

_embedded.categories[]._id

String

The immutable, unique identifier of the requested resource.

_embedded.categories[].name

String

The name of the product collection.

_embedded.categories[].label

String

The label of the product collection.

_embedded.categories[].type

String

The type of the product collection. Can be SMART or MANUAL.

_embedded.categories[].query

Object

The JSON query to retrieve products according to Elasticsearch Query DSL.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1237

{
  "_embedded" : {
    "categories" : [ {
      "name" : "Power Bars",
      "label" : "power-bar",
      "type" : "SMART",
      "query" : { "bool": { "filter": { "term": { "tags": "power-bar" }}}},
      "_id" : "75fe0098-29bc-408f-8c61-d31b424bc787",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/categories/75fe0098-29bc-408f-8c61-d31b424bc787"
        },
        "category" : {
          "href" : "https://api-shop.beyondshop.cloud/api/categories/75fe0098-29bc-408f-8c61-d31b424bc787"
        }
      }
    }, {
      "name" : "Sale",
      "label" : "sale",
      "type" : "MANUAL",
      "query" : {"bool":{"filter":[{"term":{"tasks":"power-bar"}}]}},
      "_id" : "b9080dae-df06-4c37-9f33-55db955df5a9",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/categories/b9080dae-df06-4c37-9f33-55db955df5a9"
        },
        "category" : {
          "href" : "https://api-shop.beyondshop.cloud/api/categories/b9080dae-df06-4c37-9f33-55db955df5a9"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories?page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

Create category

A POST request is used to create a category.

Required scopes

catg:c

Request body properties

Path Type Description Constraints

name

String

The name of the product collection.

Length must be between 0 and 255 inclusive. Must not be empty

label

String

The label of the product collection.

Length must be between 0 and 255 inclusive

type

String

The type of the product collection. Can be SMART or MANUAL.

Must not be null

query

Object

The JSON query to retrieve products according to Elasticsearch Query DSL.

Must not be null

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/categories' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{"name":"Power Bars","label":"power-bar","type":"SMART","query":{"bool":{"filter":{"term":{"tags":"power-bar"}}}}}'

Response body properties

Path Type Description

name

String

The name of the product collection.

label

String

The label of the product collection.

type

String

The type of the product collection. Can be SMART or MANUAL.

query

Object

The JSON query to retrieve products according to Elasticsearch Query DSL.

_id

String

The immutable, unique identifier of the requested resource.

_links

Object

See Hypermedia

Example response

HTTP/1.1 201 Created
Location: https://api-shop.beyondshop.cloud/api/categories/ffb628f4-8c86-4401-b4ab-1bebc4b96627
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 432

{
  "name" : "Power Bars",
  "label" : "power-bar",
  "type" : "SMART",
  "query" : {"bool":{"filter":{"term":{"tags":"power-bar"}}}},
  "_id" : "ffb628f4-8c86-4401-b4ab-1bebc4b96627",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/ffb628f4-8c86-4401-b4ab-1bebc4b96627"
    },
    "category" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/ffb628f4-8c86-4401-b4ab-1bebc4b96627"
    }
  }
}

Show category details

A GET request is used to retrieve the details of a category.

Required scopes

catg:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/categories/19bf5c84-5703-46c5-87ae-84b684671adb' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

name

String

The name of the product collection.

label

String

The label of the product collection.

type

String

The type of the product collection. Can be SMART or MANUAL.

query

Object

The JSON query to retrieve products according to Elasticsearch Query DSL.

_id

String

The immutable, unique identifier of the requested resource.

_links

Object

See Hypermedia

Links

Relation Description

category

The templated self link of the product collection. Current representation of the resource. See Hypermedia.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 441

{
  "name" : "Power Bars",
  "label" : "power-bar",
  "type" : "SMART",
  "query" : { "bool": { "filter": { "term": { "tags": "power-bar" }}}},
  "_id" : "19bf5c84-5703-46c5-87ae-84b684671adb",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/19bf5c84-5703-46c5-87ae-84b684671adb"
    },
    "category" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/19bf5c84-5703-46c5-87ae-84b684671adb"
    }
  }
}

Update all category properties

A PUT request is issued to update all category properties with application/json content type.

Required scopes

catg:u

Request body properties

Path Type Description Constraints

name

String

The name of the product collection.

Length must be between 0 and 255 inclusive. Must not be empty

label

String

The label of the product collection.

Length must be between 0 and 255 inclusive

type

String

The type of the product collection. Can be SMART or MANUAL.

Must not be null

query

Object

The JSON query to retrieve products according to Elasticsearch Query DSL.

Must not be null

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/categories/d754163b-ca89-4f65-85a6-c9e5ed842f5d' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{"name":"High Protein Power Bars","label":"high-protein","type":"MANUAL","query":{"bool":{"filter":[{"term":{"tasks":"power-bar"}}]}}}'

Response body properties

Path Type Description

name

String

The name of the product collection.

label

String

The label of the product collection.

type

String

The type of the product collection. Can be SMART or MANUAL.

query

Object

The JSON query to retrieve products according to Elasticsearch Query DSL.

_id

String

The immutable, unique identifier of the requested resource.

_links

Object

See Hypermedia

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 452

{
  "name" : "High Protein Power Bars",
  "label" : "high-protein",
  "type" : "MANUAL",
  "query" : {"bool":{"filter":[{"term":{"tasks":"power-bar"}}]}},
  "_id" : "d754163b-ca89-4f65-85a6-c9e5ed842f5d",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/d754163b-ca89-4f65-85a6-c9e5ed842f5d"
    },
    "category" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/d754163b-ca89-4f65-85a6-c9e5ed842f5d"
    }
  }
}

Update category partially (json patch)

A PATCH request is used to update a category partially with json patch content type.

Required scopes

catg:u

Request body properties

Path Type Description

.[]

Array

A list of JSON Patch operations.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/categories/fd998cad-c751-4ff8-baca-9804d79f8c5c' -i -X PATCH \
    -H 'Content-Type: application/json-patch+json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '[{"op":"test","path":"/name","value":"Power Bars"},{"op":"replace","path":"/name","value":"High Protein Power Bars"},{"op":"replace","path":"/type","value":"MANUAL"},{"op":"replace","path":"/query","value":{"bool":{"filter":[{"term":{"tasks":"power-bar"}}]}}}]'

Response body properties

Path Type Description

name

String

The name of the product collection.

label

String

The label of the product collection.

type

String

The type of the product collection. Can be SMART or MANUAL.

query

Object

The JSON query to retrieve products according to Elasticsearch Query DSL.

_id

String

The immutable, unique identifier of the requested resource.

_links

Object

See Hypermedia

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 449

{
  "name" : "High Protein Power Bars",
  "label" : "power-bar",
  "type" : "MANUAL",
  "query" : {"bool":{"filter":[{"term":{"tasks":"power-bar"}}]}},
  "_id" : "fd998cad-c751-4ff8-baca-9804d79f8c5c",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/fd998cad-c751-4ff8-baca-9804d79f8c5c"
    },
    "category" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/fd998cad-c751-4ff8-baca-9804d79f8c5c"
    }
  }
}

Update category partially (json)

A PATCH request is used to update a category partially with json content type.

Required scopes

catg:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/categories/32809141-cd99-4af5-9e83-e737e8a46283' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{"name":"High Protein Power Bars","type":"MANUAL","query":{"bool":{"filter":[{"term":{"tasks":"power-bar"}}]}}}'

Response body properties

Path Type Description

name

String

The name of the product collection.

label

String

The label of the product collection.

type

String

The type of the product collection. Can be SMART or MANUAL.

query

Object

The JSON query to retrieve products according to Elasticsearch Query DSL.

_id

String

The immutable, unique identifier of the requested resource.

_links

Object

See Hypermedia

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 449

{
  "name" : "High Protein Power Bars",
  "label" : "power-bar",
  "type" : "MANUAL",
  "query" : {"bool":{"filter":[{"term":{"tasks":"power-bar"}}]}},
  "_id" : "32809141-cd99-4af5-9e83-e737e8a46283",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/32809141-cd99-4af5-9e83-e737e8a46283"
    },
    "category" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/32809141-cd99-4af5-9e83-e737e8a46283"
    }
  }
}

Delete category

A DELETE request is used to delete a category.

Required scopes

catg:d

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/categories/1d969f4e-a576-48c2-9e9f-34b2ffc81989' -i -X DELETE \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 204 No Content

Show product category details

A GET request is used to retrieve the details of a product category.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/product-view/categories/0ea8f404-d5ba-4617-a008-de915d5f8cec' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json'

Response body properties

Path Type Description

_id

String

The unique identifier of the category.

name

String

The name of the category.

label

String

The label of the category.

type

String

The type of the category. Can be SMART or MANUAL.

_links

Object

See Hypermedia

Links

Relation Description

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 533

{
  "type" : "SMART",
  "name" : "Power Bars",
  "label" : "power-bar",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/0ea8f404-d5ba-4617-a008-de915d5f8cec"
    },
    "category" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/0ea8f404-d5ba-4617-a008-de915d5f8cec"
    },
    "products" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/0ea8f404-d5ba-4617-a008-de915d5f8cec/products"
    }
  },
  "_id" : "0ea8f404-d5ba-4617-a008-de915d5f8cec"
}

List product categories

A GET request is used to list all product categories.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/product-view/categories' -i -X GET \
    -H 'Content-Type: application/hal+json' \
    -H 'Accept: application/hal+json'

Response body properties

Path Type Description

_embedded.categories[]._id

String

The unique identifier of the category.

_embedded.categories[].name

String

The name of the category.

_embedded.categories[].label

String

The label of the category.

_embedded.categories[].type

String

The type of the category. Can be SMART or MANUAL.

_embedded.categories[]._links

Object

The links to receive further information related to this category.

_links

Object

See Hypermedia

page

Object

See Pagination

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1457

{
  "_embedded" : {
    "categories" : [ {
      "type" : "SMART",
      "name" : "Books",
      "label" : "books",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/0bccd47e-721d-430f-a4b3-87fff3953bcb"
        },
        "category" : {
          "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/0bccd47e-721d-430f-a4b3-87fff3953bcb"
        },
        "products" : {
          "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/0bccd47e-721d-430f-a4b3-87fff3953bcb/products"
        }
      },
      "_id" : "0bccd47e-721d-430f-a4b3-87fff3953bcb"
    }, {
      "type" : "SMART",
      "name" : "Power Bars",
      "label" : "power-bar",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/1fa2f145-0454-4caf-a57f-1cfde37a2eee"
        },
        "category" : {
          "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/1fa2f145-0454-4caf-a57f-1cfde37a2eee"
        },
        "products" : {
          "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/1fa2f145-0454-4caf-a57f-1cfde37a2eee/products"
        }
      },
      "_id" : "1fa2f145-0454-4caf-a57f-1cfde37a2eee"
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories?page=0&size=40"
    }
  },
  "page" : {
    "size" : 40,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

List products of category

A GET request is used to list all products of a category.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/product-view/categories/4e03fc12-a866-46b8-8a2a-100617e67d63/products' -i -X GET \
    -H 'Content-Type: application/hal+json' \
    -H 'Accept: application/hal+json'

Response body properties

Path Type Description

_embedded.products[]._id

String

The unique identifier of the product.

_embedded.products[].sku

String

The stock keeping unit (SKU) corresponding to the product.

_embedded.products[].name

String

The name of the product.

_embedded.products[].manufacturer

String

The manufacturer of the product.

_embedded.products[].salesPrice

Object

The price of the product.

_embedded.products[].salesPrice.amount

Number

The amount of the offer price.

_embedded.products[].salesPrice.currency

String

The currency of the offer price.

_embedded.products[].minSalesPrice

Object

The minimum price of the product.

_embedded.products[].maxSalesPrice

Object

The maximum price of the product.

_embedded.products[].listPrice

Object

The list price of the product, also known as the manufacturer’s suggested retail price or recommended retail price.

_embedded.products[].listPrice.amount

Number

The amount of the list price.

_embedded.products[].listPrice.currency

String

The currency of the list price.

_embedded.products[].manufacturerPrice

Object

The list price of the product, also known as the manufacturer’s suggested retail price or recommended retail price.

_embedded.products[].manufacturerPrice.amount

Number

The amount of the manufacturer’s suggested retail price.

_embedded.products[].manufacturerPrice.currency

String

The currency of the manufacturer’s suggested retail price.

_embedded.products[].onSale

Boolean

Indicates if the product is on offer. Can be true or false.

_embedded.products[].listPriceText

Null

The text that comes along with the list price.

_embedded.products[].shippingWeight

Number

The weight of the product including packaging in g.

_embedded.products[].shippingDimension

Object

The shipping dimensions of the product displayed in mm.

_embedded.products[].shippingDimension.length

Number

The length of the product including packaging in mm.

_embedded.products[].shippingDimension.width

Number

The width of the product including packaging in mm.

_embedded.products[].shippingDimension.height

Number

The height of the product including packaging in mm.

_embedded.products[].refPrice

Object

The price information scaled to a standardised base unit.

_embedded.products[].refPrice.refQuantity

Number

The reference quantity the product’s reference price is calculated on.

_embedded.products[].refPrice.unit

String

The unit corresponding to the quanity.

_embedded.products[].refPrice.quantity

Number

The actual quantity in the product.

_embedded.products[].refPrice.price

Object

The actual reference price.

_embedded.products[].refPrice.price.amount

Number

The amount of reference price.

_embedded.products[].refPrice.price.currency

String

The currency of reference price.

_embedded.products[].availabilityState

String

The current availability state for the product. Can be IN_STOCK, LOW_STOCK, or OUT_OF_STOCK.

_embedded.products[].variationAttributes

Array

The variation attributes with its values.

_embedded.products[].variationAttributes[].displayName

Varies

The name of the variation attribute.

_embedded.products[].variationAttributes[].values

Varies

The values of the variation attribute.

_embedded.products[]._links

Object

The links to receive further information related to the product.

_embedded.products[].productIdentifiers[]

Array

The list of identifiers of the product.

_embedded.products[].productIdentifiers[].type

String

The product code to identify and classify the product.

_embedded.products[].productIdentifiers[].value

String

The actual value of the product identifier.

_links

Object

See Hypermedia

page

Object

See Pagination

Links

Relation Description

_embedded.products[]._links.default-image-data

A link relation to the default image URL. See also Hypermedia.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 3053

{
  "_embedded" : {
    "products" : [ {
      "_id" : "00000000-0000-0000-0000-000000000001",
      "sku" : "EB001",
      "name" : "High Protein Power Bar (Pack of 5)",
      "manufacturer" : "Protein Bar Makers",
      "salesPrice" : {
        "amount" : 4.95,
        "currency" : "EUR"
      },
      "onSale" : false,
      "listPrice" : null,
      "listPriceText" : null,
      "manufacturerPrice" : null,
      "refPrice" : null,
      "availabilityState" : "LOW_STOCK",
      "shippingWeight" : 190,
      "shippingDimension" : {
        "length" : 19,
        "width" : 18,
        "height" : 17
      },
      "productIdentifiers" : [ ],
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/product-view/products/00000000-0000-0000-0000-000000000001"
        },
        "product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/product-view/products/00000000-0000-0000-0000-000000000001"
        }
      }
    }, {
      "_id" : "c1a46f5f-7648-4ebc-ad2f-f50ee3cce038",
      "name" : "Rioja Castillo de Puerto (2013)",
      "manufacturer" : "Grape Vineyard",
      "salesPrice" : {
        "amount" : 8.7,
        "currency" : "EUR"
      },
      "minSalesPrice" : {
        "amount" : 8.7,
        "currency" : "EUR"
      },
      "maxSalesPrice" : {
        "amount" : 8.7,
        "currency" : "EUR"
      },
      "onSale" : true,
      "listPrice" : {
        "amount" : 10.95,
        "currency" : "EUR"
      },
      "listPriceText" : null,
      "manufacturerPrice" : {
        "amount" : 99.95,
        "currency" : "EUR"
      },
      "refPrice" : {
        "refQuantity" : 1,
        "unit" : "LITER",
        "quantity" : 0.75,
        "price" : {
          "amount" : 11.6,
          "currency" : "EUR"
        }
      },
      "availabilityState" : "IN_STOCK",
      "shippingWeight" : 100,
      "shippingDimension" : {
        "length" : 1500,
        "width" : 1000,
        "height" : 2000
      },
      "variationAttributes" : [ {
        "displayName" : "Volume",
        "values" : [ "0.2l", "0.7l", "1.5l" ]
      } ],
      "productIdentifiers" : [ {
        "type" : "EAN",
        "value" : "501234567890"
      }, {
        "type" : "UPC",
        "value" : "425261"
      } ],
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/rioja-01.jpg?hash=e9a1ce5c0c6abfebec8fb1f6faf77dca7e6e7777{&width,height,upscale}",
          "templated" : true
        },
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/product-view/products/c1a46f5f-7648-4ebc-ad2f-f50ee3cce038"
        },
        "product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/product-view/products/c1a46f5f-7648-4ebc-ad2f-f50ee3cce038"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/4e03fc12-a866-46b8-8a2a-100617e67d63/products?page=0&size=40"
    }
  },
  "page" : {
    "size" : 40,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

List product categories assigned to an existing product

A GET request is used to list all product categories a product is part of using the request parameter productId.

For the response body properties see category list structure.

Request parameters

Parameter Description

productId

The unique identifier of the product.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/product-view/categories/search/find-by-product?productId=c4b1e6ed-9891-4b65-8078-14efcfc04777' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1536

{
  "_embedded" : {
    "categories" : [ {
      "type" : "SMART",
      "name" : "category that loves everyone",
      "label" : null,
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/dac36f4f-1b76-45f3-b10a-cae9d8020bb7"
        },
        "category" : {
          "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/dac36f4f-1b76-45f3-b10a-cae9d8020bb7"
        },
        "products" : {
          "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/dac36f4f-1b76-45f3-b10a-cae9d8020bb7/products"
        }
      },
      "_id" : "dac36f4f-1b76-45f3-b10a-cae9d8020bb7"
    }, {
      "type" : "MANUAL",
      "name" : "category that matches product 1 in a complicated way",
      "label" : null,
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/6a8c7ee3-aee0-410f-b493-e88cd9951047"
        },
        "category" : {
          "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/6a8c7ee3-aee0-410f-b493-e88cd9951047"
        },
        "products" : {
          "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/6a8c7ee3-aee0-410f-b493-e88cd9951047/products"
        }
      },
      "_id" : "6a8c7ee3-aee0-410f-b493-e88cd9951047"
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/search/find-by-product?page=0&size=40"
    }
  },
  "page" : {
    "size" : 40,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

Search matching product categories for product

This POST request is read-only and cannot create data. It is used to search for categories a new product will be part of using the request body. An existing product can also be part of the call. This endpoint can handle all properties a product can have, see List products.

For the request body properties see product structure. For the response body properties see category list structure.

Request parameters

Parameter Description

Request body properties

Path Type Description

tags

Array

The tags assigned to a product.

manufacturer

String

The manufacturer of the product.

salesPrice

Object

The price of the product.

salesPrice.amount

Number

The amount of the offer price.

salesPrice.currency

String

The currency of the offer price.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/product-view/categories/search/find-by-product' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -d '{
  "tags" : [ "books" ],
  "manufacturer" : "The Standard Manufacturer",
  "salesPrice" : {
    "amount" : 10.0,
    "currency" : "EUR"
  }
}'

Response body properties

Path Type Description

_embedded.categories[]._id

String

The unique identifier of the category.

_embedded.categories[].label

String

The label of the category.

_embedded.categories[].name

String

The name of the category.

_embedded.categories[].type

String

The type of the category. Can be SMART or MANUAL.

_embedded.categories[]._links

Object

The links to receive further information related to this category.

_links

Object

See Hypermedia

page

Object

See Pagination

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 881

{
  "_embedded" : {
    "categories" : [ {
      "type" : "SMART",
      "name" : "Books",
      "label" : "books",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/65615eca-a88d-49f3-8801-112aa6d552d4"
        },
        "category" : {
          "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/65615eca-a88d-49f3-8801-112aa6d552d4"
        },
        "products" : {
          "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/65615eca-a88d-49f3-8801-112aa6d552d4/products"
        }
      },
      "_id" : "65615eca-a88d-49f3-8801-112aa6d552d4"
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/search/find-by-product?page=0&size=40"
    }
  },
  "page" : {
    "size" : 40,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

Find product category by label

A GET request is used to find a product category by its unique label.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/product-view/categories/search/find-by-label?label=power-bar' -i -X GET \
    -H 'Content-Type: application/hal+json' \
    -H 'Accept: application/hal+json'

Response body properties

Path Type Description

_id

String

The unique identifier of the category.

name

String

The name of the category.

label

String

The label of the category.

type

String

The type of the category. Can be SMART or MANUAL.

_links

Object

See Hypermedia

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 533

{
  "type" : "SMART",
  "name" : "Power Bars",
  "label" : "power-bar",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/3dff1c0a-454b-4933-bbd7-8da9a31a37db"
    },
    "category" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/3dff1c0a-454b-4933-bbd7-8da9a31a37db"
    },
    "products" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-view/categories/3dff1c0a-454b-4933-bbd7-8da9a31a37db/products"
    }
  },
  "_id" : "3dff1c0a-454b-4933-bbd7-8da9a31a37db"
}

Checkout

The checkout settings resources contain information about the minimum order value of a shop as well as indicate customer consent to the general terms and conditions of a shop.

List checkout settings

A GET request is used to retrieve the checkout settings.

Required scopes

cset:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/checkout-settings' -i -X GET \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Links

Relation Description

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 217

{
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 4
  },
  "mustAcceptTermsAndConditions" : false,
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/checkout-settings"
    }
  }
}

Update checkout settings

A PUT request is used to update the checkout settings.

Required scopes

cset:u

Request body properties

Path Type Description

minimumOrderValue.currency

String

The currency of the minimum order value of this shop.

minimumOrderValue.amount

Number

The amount of the minimum order value of this shop.

mustAcceptTermsAndConditions

Boolean

Indicates if the customer has to explicitly consent to the terms and conditions before buying something. Can be true or false.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/checkout-settings' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d ' {
   "minimumOrderValue" : {
     "currency" : "EUR",
     "amount" : 50
   },
   "mustAcceptTermsAndConditions" : true
 }'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 217

{
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 50
  },
  "mustAcceptTermsAndConditions" : true,
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/checkout-settings"
    }
  }
}

Orders

The orders resource is used to manage the orders of a shop. This includes all processes related to billing, shipping, payments, invoicing, as well as refunds, returns, and cancelations.

List orders

A GET request is used to list all orders of the shop in a paged way. Each item in the response represents a summary of the order data.

Required scopes

ordr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_embedded.orders[]

Array

The list of orders as documented in Show order details.

_links

Object

See Hypermedia

page

Object

See Pagination

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 12016

{
  "_embedded" : {
    "orders" : [ {
      "_id" : "d42b5c79-a556-4a9a-8ea8-fba950559eb0",
      "createdAt" : "2019-10-14T10:08:37.931",
      "cartId" : "827f6d34-e10d-4101-b0b2-8140a99e3f9f",
      "currency" : "EUR",
      "taxModel" : "GROSS",
      "taxable" : false,
      "testOrder" : false,
      "termsAndConditionsExplicitlyAccepted" : false,
      "productLineItems" : [ {
        "_id" : "81fa681c-0a39-4912-8aa9-cbcda60f8a9e",
        "product" : {
          "_id" : "2e48ab48-f991-40d1-9e89-9a8c481134b9",
          "sku" : "sh-001",
          "name" : "Soft Walk Ultra - Nibok Men's",
          "essentialFeatures" : "Inner Material: Synthetic. Sole: Rubber. Upper Material: Leather.",
          "shippingWeight" : 190,
          "defaultImageDataUri" : "http://your.image.hoster.com/randomimage.png",
          "variationAttributeValues" : [ {
            "displayName" : "Size",
            "value" : "40 EU"
          } ],
          "_links" : {
            "default-image-data" : {
              "href" : "https://api-shop.beyondshop.cloud/api/http:/your.image.hoster.com/randomimage.png"
            },
            "variation-product" : {
              "href" : "https://api-shop.beyondshop.cloud/api/api/products/dfa7d18f-9ed1-4cb7-8770-9de60a13da8b"
            }
          }
        },
        "quantity" : 3,
        "initialQuantity" : 3,
        "unitPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 2.5
        },
        "lineItemPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 7.5
        },
        "initialLineItemPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 7.5
        },
        "lineItemTax" : {
          "taxClass" : "REGULAR",
          "taxRate" : 0.19,
          "currency" : "EUR",
          "amount" : 1.197
        },
        "unshipped" : {
          "quantity" : 3,
          "amount" : null
        },
        "shipped" : {
          "quantity" : 0,
          "amount" : null
        },
        "pending" : {
          "quantity" : 0,
          "amount" : null
        },
        "returned" : {
          "quantity" : 0,
          "amount" : {
            "currency" : "EUR",
            "amount" : 0
          }
        },
        "broken" : {
          "quantity" : 0,
          "amount" : {
            "currency" : "EUR",
            "amount" : 0
          }
        },
        "canceled" : {
          "quantity" : 0,
          "amount" : {
            "currency" : "EUR",
            "amount" : 0
          }
        }
      }, {
        "_id" : "f4a28579-f548-4e96-81d6-c9b01f805b16",
        "product" : {
          "_id" : "cc6f2bd4-92b1-4c21-a75d-2d9f12c343d3",
          "sku" : "EB001",
          "name" : "High Protein Power Bar (Pack of 5)",
          "essentialFeatures" : "Preservative-free. No added sweeteners. Vegan.",
          "shippingWeight" : 190,
          "defaultImageDataUri" : "http://your.image.hoster.com/randomimage.png",
          "variationAttributeValues" : [ {
            "displayName" : "flavor",
            "value" : "Salted Caramel"
          } ],
          "_links" : {
            "default-image-data" : {
              "href" : "https://api-shop.beyondshop.cloud/api/http:/your.image.hoster.com/randomimage.png"
            },
            "variation-product" : {
              "href" : "https://api-shop.beyondshop.cloud/api/api/products/d753e749-5835-49d5-aaa0-7aa716647adf"
            }
          }
        },
        "quantity" : 5,
        "initialQuantity" : 5,
        "unitPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 9.99
        },
        "lineItemPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 49.95
        },
        "initialLineItemPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 49.95
        },
        "lineItemTax" : {
          "taxClass" : "REGULAR",
          "taxRate" : 0.19,
          "currency" : "EUR",
          "amount" : 7.9743
        },
        "unshipped" : {
          "quantity" : 5,
          "amount" : null
        },
        "shipped" : {
          "quantity" : 0,
          "amount" : null
        },
        "pending" : {
          "quantity" : 0,
          "amount" : null
        },
        "returned" : {
          "quantity" : 0,
          "amount" : {
            "currency" : "EUR",
            "amount" : 0
          }
        },
        "broken" : {
          "quantity" : 0,
          "amount" : {
            "currency" : "EUR",
            "amount" : 0
          }
        },
        "canceled" : {
          "quantity" : 0,
          "amount" : {
            "currency" : "EUR",
            "amount" : 0
          }
        }
      } ],
      "shippingLineItem" : {
        "lineItemPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 19.99
        },
        "initialLineItemPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 19.99
        },
        "taxClass" : "REGULAR",
        "shippingMethod" : {
          "id" : "b3cffcff-17e8-47ea-9954-9c6522cfb952",
          "name" : "Standard",
          "description" : "Standard shipping. Delivery within 3-4 days.",
          "freeShippingValue" : {
            "currency" : "EUR",
            "amount" : 400
          },
          "fixedPrice" : {
            "taxModel" : "GROSS",
            "currency" : "EUR",
            "amount" : 19.99
          },
          "weightBasedPrice" : null
        },
        "lineItemTaxes" : [ {
          "taxClass" : "REGULAR",
          "taxRate" : 0.19,
          "currency" : "EUR",
          "amount" : 3.192
        } ]
      },
      "paymentLineItem" : {
        "lineItemPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 0
        },
        "initialLineItemPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 0
        },
        "taxClass" : "REGULAR",
        "paymentMethod" : {
          "id" : "6b74d309-30c4-403b-834d-59d3dd342dfe",
          "name" : "PayPal",
          "description" : "Pay by PayPal.",
          "discountOrFee" : {
            "type" : "ABSOLUTE",
            "absoluteValue" : {
              "taxModel" : "GROSS",
              "currency" : "EUR",
              "amount" : 0
            },
            "percentageValue" : null
          },
          "onlinePayment" : false
        },
        "lineItemTaxes" : [ {
          "taxClass" : "REGULAR",
          "taxRate" : 0.19,
          "currency" : "EUR",
          "amount" : 0
        } ]
      },
      "customerEmail" : "a.alsterh@example.com",
      "subtotal" : {
        "currency" : "EUR",
        "amount" : 57.45
      },
      "grandTotal" : {
        "currency" : "EUR",
        "amount" : 77.44
      },
      "balanceDue" : {
        "currency" : "EUR",
        "amount" : 77.44
      },
      "netTotal" : {
        "currency" : "EUR",
        "amount" : 68.2687
      },
      "taxTotal" : {
        "currency" : "EUR",
        "amount" : 9.1713
      },
      "initialSubtotal" : {
        "currency" : "EUR",
        "amount" : 57.45
      },
      "initialGrandTotal" : {
        "currency" : "EUR",
        "amount" : 77.44
      },
      "initialBalanceDue" : {
        "currency" : "EUR",
        "amount" : 77.44
      },
      "initialNetTotal" : {
        "currency" : "EUR",
        "amount" : 68.2687
      },
      "initialTaxTotal" : {
        "currency" : "EUR",
        "amount" : 9.1713
      },
      "taxes" : [ {
        "taxClass" : "REGULAR",
        "taxRate" : 0.19,
        "currency" : "EUR",
        "amount" : 9.1713
      } ],
      "shippingAddress" : {
        "salutation" : "Mrs",
        "gender" : "FEMALE",
        "company" : "Astrid Alster GmbH",
        "title" : null,
        "firstName" : "Astrid",
        "middleName" : "Agnes",
        "lastName" : "Alster",
        "street" : "Alsterwasserweg",
        "houseNumber" : "2",
        "street2" : "Erdgeschoss",
        "addressExtension" : "Hinterhof",
        "postalCode" : "20999",
        "dependentLocality" : "Seevetal",
        "city" : "Alsterwasser",
        "country" : "DE",
        "state" : "Hamburg",
        "email" : "a.alsterh@example.com",
        "phone" : "(800) 555-0102",
        "mobile" : "(800) 555-0103",
        "doorCode" : "456",
        "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "Erdgeschoss", "Hinterhof", "Seevetal", "20999 Alsterwasser", "GERMANY" ]
      },
      "billingAddress" : {
        "salutation" : "Mrs",
        "gender" : "FEMALE",
        "company" : "Astrid Alster GmbH",
        "title" : null,
        "firstName" : "Astrid",
        "middleName" : "Agnes",
        "lastName" : "Alster",
        "street" : "Alsterwasserweg",
        "houseNumber" : "2",
        "street2" : "Erdgeschoss",
        "addressExtension" : "Hinterhof",
        "postalCode" : "20999",
        "dependentLocality" : "Seevetal",
        "city" : "Alsterwasser",
        "country" : "DE",
        "state" : "Hamburg",
        "email" : "a.alsterh@example.com",
        "phone" : "(800) 555-0102",
        "mobile" : "(800) 555-0103",
        "vatId" : "DE123456789",
        "taxNumber" : "HRE 987654/32123/864516",
        "birthDate" : "1985-05-11",
        "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "Erdgeschoss", "Hinterhof", "Seevetal", "20999 Alsterwasser", "GERMANY" ]
      },
      "paymentStatus" : "PENDING",
      "shippingStatus" : "UNSHIPPED",
      "canceled" : false,
      "orderNumber" : "10001",
      "customerComment" : "Please send with UPS.",
      "orderNote" : "Already paid.",
      "paymentNote" : "Reference EDB85BEA2DAE436E90C1E2027A0F012A",
      "externalPaymentId" : "6b2d2fg1-05c9-4159-146c-5fy2fe596z26",
      "externalPaymentUri" : "https://example.com/referral",
      "entryDate" : "2019-10-14T10:08:37.911",
      "totalReceived" : {
        "currency" : "EUR",
        "amount" : 0
      },
      "totalRefunded" : {
        "currency" : "EUR",
        "amount" : 0
      },
      "openAmount" : {
        "currency" : "EUR",
        "amount" : 77.44
      },
      "marketingChannel" : "Google Shopping",
      "marketingSubchannel" : "Summer Sale",
      "salesChannel" : "Retail store",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/d42b5c79-a556-4a9a-8ea8-fba950559eb0"
        },
        "order" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/d42b5c79-a556-4a9a-8ea8-fba950559eb0"
        },
        "order-note" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/d42b5c79-a556-4a9a-8ea8-fba950559eb0/order-note"
        },
        "processes" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/d42b5c79-a556-4a9a-8ea8-fba950559eb0/processes"
        },
        "events" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/d42b5c79-a556-4a9a-8ea8-fba950559eb0/events"
        },
        "cancel" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/d42b5c79-a556-4a9a-8ea8-fba950559eb0/cancel"
        },
        "create-invoice" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/d42b5c79-a556-4a9a-8ea8-fba950559eb0/create-invoice"
        },
        "terms-and-conditions-pdf" : {
          "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/terms-and-conditions.pdf?hash=238734684735643875634578213"
        },
        "right-of-withdrawal-pdf" : {
          "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/right-of-withdrawal.pdf?hash=647563475863487"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders?page=0&size=20&sort=createdAt,desc"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

Show order details

A GET request is used to retrieve the details of an order.

Required scopes

ordr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/0ed0ccf1-9cea-42e6-81a3-aead8880157b' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_id

String

The unique identifier of the order.

cartId

String

The ID of the cart this order has been created from (if existing).

createdAt

String

The date and time the order was technically created in the system. According to ISO 8601. Can deviate from entryDate, e.g. because the order was originally created earlier or in another system.

entryDate

String

The date and time of the actual creation of this order from a business perspective. Can deviate from createdAt.

currency

String

The currency in which the order was entered.

taxModel

String

The tax model that applies for this order.

taxable

Boolean

Indicates if a tax applies for this order. Can be true or false.

testOrder

Boolean

Indicates if this order is a test order. Can be true or false.

termsAndConditionsExplicitlyAccepted

Boolean

Indicates if the customer explicitly accepted the shop’s terms and conditions before ordering. Can be true or false.

orderNumber

String

The automatically generated order number.

customerComment

String

A comment from the customer regarding their order.

customerEmail

String

The email address of the registered customer.

salesChannel

String

The sales channel for this order, such as an online shop, point of sale, or a retail store.

marketingChannel

String

The marketing channel for this order, such as a newsletter campaign, Google Shopping, or a Buy Button that’s implemented on a blog.

marketingSubchannel

String

The marketing subchannel for this order, such as a specific newsletter of a newsletter campaign, e.g. a Summer Sale that’s promoted on a blog, or a Winter Special that’s promoted on Facebook.

productLineItems[].quantity

Number

The value of the quantity for the product line item.

productLineItems[].initialQuantity

Number

The initial quantity for the product line item.

productLineItems[].unitPrice.amount

Number

The amount of the unit price for the product line item.

productLineItems[].unitPrice.currency

String

The currency of the single product line item price.

productLineItems[].unitPrice.taxModel

String

The tax model of the unit price for a product line item.

productLineItems[].lineItemPrice.amount

Number

The amount of the line item price for a product line item.

productLineItems[].lineItemPrice.currency

String

The currency of the line item price for a product line item.

productLineItems[].lineItemPrice.taxModel

String

The tax model of the line item price for a product line item.

productLineItems[].initialLineItemPrice.amount

Number

The initial amount of the line item price for a product line item.

productLineItems[].initialLineItemPrice.currency

String

The currency of the initial line item price for a product line item.

productLineItems[].initialLineItemPrice.taxModel

String

The tax model of the initial line item price for a product line item.

productLineItems[].lineItemTax.taxRate

Number

The tax rate of a product line item.

productLineItems[].lineItemTax.taxClass

String

The tax class of a product line item. Can be REGULAR, REDUCED, or EXEMPT.

productLineItems[].lineItemTax.amount

Number

The tax amount of a product line item.

productLineItems[].lineItemTax.currency

String

The currency of the tax for a product line item.

productLineItems[].product._id

String

The ID of the product for this product line item.

productLineItems[].product.sku

String

The stock keeping unit (SKU) corresponding to the product in this product line item.

productLineItems[].product.name

String

The name of the product in this product line item.

productLineItems[].product.essentialFeatures

String

The essential product properties of the product in this product line item. Shown in the cart and checkout. In Germany mandatory field in online shops according to §312j Abs. 2 BGB (German Civil Code).

productLineItems[].product.shippingWeight

Number

The shipping weight of the product in this product line item.

productLineItems[].product._links.default-image-data

Object

The link to the product default image.

productLineItems[].product._links.variation-product

Object

The optional link to the variation product if the product line item is a variation.

productLineItems[].product.defaultImageDataUri

String

The relative product default image URI.

productLineItems[]._id

String

The ID of the product line item.

productLineItems[].unshipped.quantity

Number

The quantity of not yet dispatched items of this product line item.

productLineItems[].unshipped.amount

Null

The amount of not yet dispatched items of this product line item.

productLineItems[].shipped.quantity

Number

The quantity of dispatched items of this product line item.

productLineItems[].shipped.amount

Null

The amount of dispatched items of this product line item.

productLineItems[].pending.quantity

Number

The quantity of pending items of this product line item.

productLineItems[].pending.amount

Null

The amount of pending items of this product line item.

productLineItems[].returned.quantity

Number

The quantity of returned items of this product line item.

productLineItems[].returned.amount

Object

The amount of returned items of this product line item.

productLineItems[].broken.quantity

Number

The quantity of broken items of this product line item.

productLineItems[].broken.amount

Object

The amount of broken items of this product line item.

productLineItems[].canceled.quantity

Number

The quantity of canceled items of this product line item.

productLineItems[].canceled.amount

Object

The amount of canceled items of this product line item.

productLineItems[].product.variationAttributeValues

Array

The variation attributes of a product with its values.

productLineItems[].product.variationAttributeValues[].displayName

String

The name of the variation attribute defined by the merchant, e.g. name, size, or color.

productLineItems[].product.variationAttributeValues[].value

String

The values for a variation attribute defined by the merchant, e.g. the detailed sizes such as S, M, L, XL.

shippingLineItem.lineItemPrice.amount

Number

The amount of the line item price for the shipping line item.

shippingLineItem.lineItemPrice.currency

String

The currency of the price for the shipping line item.

shippingLineItem.lineItemPrice.taxModel

String

The tax model of the line item price for the shipping line item.

shippingLineItem.initialLineItemPrice.amount

Number

The amount of the initial line item price for the shipping line item.

shippingLineItem.initialLineItemPrice.currency

String

The currency of the initial price for the shipping line item.

shippingLineItem.initialLineItemPrice.taxModel

String

The tax model of the initial line item price for the shipping line item.

shippingLineItem.taxClass

String

The tax class of the shipping line item. Can be REGULAR, REDUCED, or EXEMPT.

shippingLineItem.lineItemTaxes

Array

The tax information for the shipping line item. The array contains one item per tax class.

shippingLineItem.shippingMethod.id

String

The ID of the shipping method in this shipping line item.

shippingLineItem.shippingMethod.name

String

The name of the shipping method in this shipping line item.

shippingLineItem.shippingMethod.description

String

The description of the shipping method in the shipping line item.

shippingLineItem.shippingMethod.freeShippingValue.amount

Number

The amount of the free shipping value of the shipping method in this shipping line item.

shippingLineItem.shippingMethod.freeShippingValue.currency

String

The currency of the free shipping amount of the shipping method.

shippingLineItem.shippingMethod.fixedPrice.amount

Number

The amount of the fixed price of the shipping method in this shipping line item (if set).

shippingLineItem.shippingMethod.fixedPrice.currency

String

The currency of the fixed price of the shipping method.

shippingLineItem.shippingMethod.fixedPrice.taxModel

String

The tax model of the fixed price of the shipping method in this shipping line item (if set).

shippingLineItem.shippingMethod.weightBasedPrice

Null

The weight-based price of the shipping method in this shipping line item (if set).

paymentLineItem.lineItemPrice.amount

Number

The amount of the product line item price for the payment line item.

paymentLineItem.lineItemPrice.currency

String

The currency of the payment line item price.

paymentLineItem.lineItemPrice.taxModel

String

The tax model of the product line item price for the payment line item.

paymentLineItem.initialLineItemPrice.amount

Number

The amount of the initial line item price for the payment line item.

paymentLineItem.initialLineItemPrice.currency

String

The currency of the initial payment line item price.

paymentLineItem.initialLineItemPrice.taxModel

String

The tax model of the initial line item price for the payment line item.

paymentLineItem.taxClass

String

The tax class of a payment line item. Can be REGULAR, REDUCED, or EXEMPT.

paymentLineItem.lineItemTaxes

Array

The tax information for the payment line item. The array contains one item per tax class.

paymentLineItem.paymentMethod.id

String

The ID of the payment method.

paymentLineItem.paymentMethod.name

String

The name of the payment method.

paymentLineItem.paymentMethod.description

String

The description of the payment method in this payment line item.

paymentLineItem.paymentMethod.discountOrFee.type

String

The type of the discountOrFee for this payment method. Can be ABSOLUTE, PERCENTAGE, or UNSUPPORTED.

paymentLineItem.paymentMethod.discountOrFee.absoluteValue.amount

Number

The amount of the absolute value of discountOrFee of the payment method in this payment line item.

paymentLineItem.paymentMethod.discountOrFee.absoluteValue.currency

String

The currency of the absolute price of the discountOrFee for this payment method.

paymentLineItem.paymentMethod.discountOrFee.absoluteValue.taxModel

String

The tax model of the absolute price of the discountOrFee for this payment method.

paymentLineItem.paymentMethod.discountOrFee.percentageValue

Null

The percentage value of the discountOrFee for this payment method.

paymentLineItem.paymentMethod.onlinePayment

Boolean

Indicates if this payment method is an online payment. Can be true or false.

initialSubtotal.amount

Number

The initial subtotal amount of the product line items.

initialSubtotal.currency

String

The currency of the initial subtotal amount.

initialGrandTotal.amount

Number

The initial total amount of the order.

initialGrandTotal.currency

String

The currency of the initial total amount of the order.

initialNetTotal.amount

Number

The initial amount of the net total.

initialNetTotal.currency

String

The currency of the initial total net amount.

initialTaxTotal.amount

Number

The initial total tax amount.

initialTaxTotal.currency

String

The currency of the initial total tax amount.

initialBalanceDue.amount

Number

The initial due balance of the order.

initialBalanceDue.currency

String

The currency of the initial balance due.

subtotal.amount

Number

The subtotal amount of the product line items.

subtotal.currency

String

The currency of the subtotal amount.

grandTotal.amount

Number

The total amount of the order.

grandTotal.currency

String

The currency of the total order amount.

netTotal.amount

Number

The amount of net total.

netTotal.currency

String

The currency of the total net amount.

taxTotal.amount

Number

The total tax amount.

taxTotal.currency

String

The currency of the total tax amount.

totalReceived.amount

Number

The total payment amount received.

totalReceived.currency

String

The currency of the total payment amount received.

totalRefunded.amount

Number

The total refunded amount.

totalRefunded.currency

String

The currency of the total refunded amount.

openAmount.amount

Number

The outstanding amount to be paid.

openAmount.currency

String

The currency of the outstanding amount to be paid.

balanceDue.amount

Number

The total amount of the order. Does not change when payments come in.

balanceDue.currency

String

The currency of the balance due.

orderNote

String

A merchant comment or note on the order.

paymentNote

String

A prompt to pay the order which will be rendered in the invoice order document. Requires a payment reference and the merchant’s bank account details.

externalPaymentId

String

The external payment reference if provided by the payment app.

externalPaymentUri

String

The link to the payment in a payment provider’s administration if provided by the payment app.

taxes[*].currency

String

The tax currency.

taxes[*].taxClass

String

The tax class. Can be REGULAR, REDUCED, or EXEMPT.

taxes[*].amount

Number

The tax amount.

taxes[*].taxRate

Number

The applied tax rate.

billingAddress

Object

The billing address of the cart. Refer to Set cart billing address for item documentation.

billingAddress.displayAddressLines

Array

The applicable billing address of the cart to be displayed.

shippingAddress

Object

The shipping address of the cart. Defaults to billing address if no shipping address is set. Refer to Set cart shipping address for item documentation.

shippingAddress.displayAddressLines

Array

The applicable shipping address of the cart to be displayed.

paymentStatus

String

The current status of the payment associated with this order. Can be PAID, PENDING, or REFUND_PENDING.

canceled

Boolean

The current cancelation status of this order. Can be true or false.

backgroundJobs

Array

Pending processes initiated via the cockpit or the API that run in the background, e.g. rendering an invoice document.

shippingStatus

String

The current shipping status of this order. Can be UNSHIPPED, PARTIALLY_SHIPPED, or SHIPPED.

_links

Object

See Hypermedia

Links

Relation Description

order

The link to the order.

order-note

The link to set an order note.

create-invoice

The link to trigger the creation of the invoice. This link exists if no invoice has been triggered so far. If the invoice has been created successfully, an invoice-pdf link appears that points to the pdf. If the creation of an invoice has been triggered, but the rendering is not yet finished, a retry-create-invoice link is available.

invoice-pdf

The link to the invoice. This link appears if the invoice has been created successfully.

invoice-correction-pdfs

The link(s) to the invoice correction pdf file(s). Appears if invoice relevant data has been changed after the invoice was created. If only one invoice was corrected, a single link object appears under this relation. If more invoices were corrected, a list of link objects will appear.

retry-create-invoice

The link to trigger a retry to create the invoice. This link exists if rendering of the invoice is not yet finished.

send-invoice

The link to trigger the sending of the invoice. This link exists if an invoice-pdf link has been rendered successfully.

right-of-withdrawal-pdf

Optional link to the pdf containing the right of withdrawal applicable for this order.

terms-and-conditions-pdf

Optional link to the pdf containing the terms and conditions applicable for this order.

delivery-note-pdf

The link to the delivery note. Appears if the delivery note has been created successfully.

processes

The link to order processes.

events

The link to the order events.

cancel

The link to cancel the order.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 10240

{
  "_id" : "0ed0ccf1-9cea-42e6-81a3-aead8880157b",
  "createdAt" : "2019-10-14T10:08:35.44",
  "cartId" : "4f97e8b8-943d-439d-86d4-0bbc4c28f496",
  "currency" : "EUR",
  "taxModel" : "GROSS",
  "taxable" : false,
  "testOrder" : false,
  "termsAndConditionsExplicitlyAccepted" : false,
  "productLineItems" : [ {
    "_id" : "8e90a97a-0887-42d7-8199-20d533a83b19",
    "product" : {
      "_id" : "64ea07d4-3706-4405-bfcd-ad7b4ac99081",
      "sku" : "sh-001",
      "name" : "Soft Walk Ultra - Nibok Men's",
      "essentialFeatures" : "Inner Material: Synthetic. Sole: Rubber. Upper Material: Leather.",
      "shippingWeight" : 190,
      "defaultImageDataUri" : "http://your.image.hoster.com/randomimage.png",
      "variationAttributeValues" : [ {
        "displayName" : "Size",
        "value" : "40 EU"
      } ],
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/http:/your.image.hoster.com/randomimage.png"
        },
        "variation-product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/products/43206e83-5b7e-4331-9d45-58d20f08d425"
        }
      }
    },
    "quantity" : 3,
    "initialQuantity" : 3,
    "unitPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2.5
    },
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 7.5
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 7.5
    },
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 1.197
    },
    "unshipped" : {
      "quantity" : 3,
      "amount" : null
    },
    "shipped" : {
      "quantity" : 0,
      "amount" : null
    },
    "pending" : {
      "quantity" : 0,
      "amount" : null
    },
    "returned" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "broken" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "canceled" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    }
  }, {
    "_id" : "a75d79da-966f-4de6-8347-4eab58c80b57",
    "product" : {
      "_id" : "99d9be77-373e-4e3f-9b58-ab932fad76e1",
      "sku" : "EB001",
      "name" : "High Protein Power Bar (Pack of 5)",
      "essentialFeatures" : "Preservative-free. No added sweeteners. Vegan.",
      "shippingWeight" : 190,
      "defaultImageDataUri" : "http://your.image.hoster.com/randomimage.png",
      "variationAttributeValues" : [ {
        "displayName" : "flavor",
        "value" : "Salted Caramel"
      } ],
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/http:/your.image.hoster.com/randomimage.png"
        },
        "variation-product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/products/17cb4e4b-a663-4af9-a3ae-f7b9346b5918"
        }
      }
    },
    "quantity" : 5,
    "initialQuantity" : 5,
    "unitPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 9.99
    },
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 49.95
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 49.95
    },
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 7.9743
    },
    "unshipped" : {
      "quantity" : 5,
      "amount" : null
    },
    "shipped" : {
      "quantity" : 0,
      "amount" : null
    },
    "pending" : {
      "quantity" : 0,
      "amount" : null
    },
    "returned" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "broken" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "canceled" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    }
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "taxClass" : "REGULAR",
    "shippingMethod" : {
      "id" : "467aa549-7835-48e3-be76-fc4578448879",
      "name" : "Standard",
      "description" : "Standard shipping. Delivery within 3-4 days.",
      "freeShippingValue" : {
        "currency" : "EUR",
        "amount" : 400
      },
      "fixedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 19.99
      },
      "weightBasedPrice" : null
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 3.192
    } ]
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "taxClass" : "REGULAR",
    "paymentMethod" : {
      "id" : "d2eaf107-5244-4008-baeb-c06d2f1fc698",
      "name" : "PayPal",
      "description" : "Pay by PayPal.",
      "discountOrFee" : {
        "type" : "ABSOLUTE",
        "absoluteValue" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 0
        },
        "percentageValue" : null
      },
      "onlinePayment" : false
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 0
    } ]
  },
  "customerEmail" : "a.alsterh@example.com",
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 68.2687
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 9.1713
  },
  "initialSubtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "initialGrandTotal" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "initialBalanceDue" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "initialNetTotal" : {
    "currency" : "EUR",
    "amount" : 68.2687
  },
  "initialTaxTotal" : {
    "currency" : "EUR",
    "amount" : 9.1713
  },
  "taxes" : [ {
    "taxClass" : "REGULAR",
    "taxRate" : 0.19,
    "currency" : "EUR",
    "amount" : 9.1713
  } ],
  "shippingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "Erdgeschoss",
    "addressExtension" : "Hinterhof",
    "postalCode" : "20999",
    "dependentLocality" : "Seevetal",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a.alsterh@example.com",
    "phone" : "(800) 555-0102",
    "mobile" : "(800) 555-0103",
    "doorCode" : "456",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "Erdgeschoss", "Hinterhof", "Seevetal", "20999 Alsterwasser", "GERMANY" ]
  },
  "billingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "Erdgeschoss",
    "addressExtension" : "Hinterhof",
    "postalCode" : "20999",
    "dependentLocality" : "Seevetal",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a.alsterh@example.com",
    "phone" : "(800) 555-0102",
    "mobile" : "(800) 555-0103",
    "vatId" : "DE123456789",
    "taxNumber" : "HRE 987654/32123/864516",
    "birthDate" : "1985-05-11",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "Erdgeschoss", "Hinterhof", "Seevetal", "20999 Alsterwasser", "GERMANY" ]
  },
  "paymentStatus" : "PENDING",
  "shippingStatus" : "UNSHIPPED",
  "canceled" : false,
  "orderNumber" : "10001",
  "customerComment" : "Please send with UPS.",
  "orderNote" : "Already paid.",
  "paymentNote" : "Reference EDB85BEA2DAE436E90C1E2027A0F012A",
  "externalPaymentId" : "6b2d2fg1-05c9-4159-146c-5fy2fe596z26",
  "externalPaymentUri" : "https://example.com/referral",
  "entryDate" : "2019-10-14T10:08:35.418",
  "totalReceived" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "totalRefunded" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "openAmount" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "marketingChannel" : "Google Shopping",
  "marketingSubchannel" : "Summer Sale",
  "salesChannel" : "Retail store",
  "backgroundJobs" : [ ],
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/0ed0ccf1-9cea-42e6-81a3-aead8880157b"
    },
    "order" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/0ed0ccf1-9cea-42e6-81a3-aead8880157b"
    },
    "order-note" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/0ed0ccf1-9cea-42e6-81a3-aead8880157b/order-note"
    },
    "processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/0ed0ccf1-9cea-42e6-81a3-aead8880157b/processes"
    },
    "events" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/0ed0ccf1-9cea-42e6-81a3-aead8880157b/events"
    },
    "cancel" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/0ed0ccf1-9cea-42e6-81a3-aead8880157b/cancel"
    },
    "create-invoice" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/0ed0ccf1-9cea-42e6-81a3-aead8880157b/create-invoice"
    },
    "right-of-withdrawal-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/right-of-withdrawal.pdf?hash=647563475863487"
    },
    "terms-and-conditions-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/terms-and-conditions.pdf?hash=238734684735643875634578213"
    }
  }
}

Show order by cart Id

A GET request is used to retrieve the details of an order by cart ID.

Required scopes

ordr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/search/find-by-cart-id?cartId=5ee387b2-690e-42fc-932c-7950dd552133' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 10241

{
  "_id" : "e96b6bee-aef2-4ac1-941b-0bbe25af5346",
  "createdAt" : "2019-10-14T10:08:23.578",
  "cartId" : "5ee387b2-690e-42fc-932c-7950dd552133",
  "currency" : "EUR",
  "taxModel" : "GROSS",
  "taxable" : false,
  "testOrder" : false,
  "termsAndConditionsExplicitlyAccepted" : false,
  "productLineItems" : [ {
    "_id" : "2011c42d-0a7a-4d8b-b1aa-90a0c9851cc2",
    "product" : {
      "_id" : "8ea4d950-14fb-47f1-ad09-37d6422151ca",
      "sku" : "sh-001",
      "name" : "Soft Walk Ultra - Nibok Men's",
      "essentialFeatures" : "Inner Material: Synthetic. Sole: Rubber. Upper Material: Leather.",
      "shippingWeight" : 190,
      "defaultImageDataUri" : "http://your.image.hoster.com/randomimage.png",
      "variationAttributeValues" : [ {
        "displayName" : "Size",
        "value" : "40 EU"
      } ],
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/http:/your.image.hoster.com/randomimage.png"
        },
        "variation-product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/products/a521095f-c4ac-4a85-bae5-f7837d8030ad"
        }
      }
    },
    "quantity" : 3,
    "initialQuantity" : 3,
    "unitPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2.5
    },
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 7.5
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 7.5
    },
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 1.197
    },
    "unshipped" : {
      "quantity" : 3,
      "amount" : null
    },
    "shipped" : {
      "quantity" : 0,
      "amount" : null
    },
    "pending" : {
      "quantity" : 0,
      "amount" : null
    },
    "returned" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "broken" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "canceled" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    }
  }, {
    "_id" : "6a0e113d-0b12-4681-8568-4c233f527ced",
    "product" : {
      "_id" : "4f90c825-9f9e-4323-8016-9e04e41f722c",
      "sku" : "EB001",
      "name" : "High Protein Power Bar (Pack of 5)",
      "essentialFeatures" : "Preservative-free. No added sweeteners. Vegan.",
      "shippingWeight" : 190,
      "defaultImageDataUri" : "http://your.image.hoster.com/randomimage.png",
      "variationAttributeValues" : [ {
        "displayName" : "flavor",
        "value" : "Salted Caramel"
      } ],
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/http:/your.image.hoster.com/randomimage.png"
        },
        "variation-product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/products/dcbdb76c-4f7e-4470-b7b7-232b9c59905e"
        }
      }
    },
    "quantity" : 5,
    "initialQuantity" : 5,
    "unitPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 9.99
    },
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 49.95
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 49.95
    },
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 7.9743
    },
    "unshipped" : {
      "quantity" : 5,
      "amount" : null
    },
    "shipped" : {
      "quantity" : 0,
      "amount" : null
    },
    "pending" : {
      "quantity" : 0,
      "amount" : null
    },
    "returned" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "broken" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "canceled" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    }
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "taxClass" : "REGULAR",
    "shippingMethod" : {
      "id" : "9811dd91-bf07-4fa6-96a6-5e8acbfe25b5",
      "name" : "Standard",
      "description" : "Standard shipping. Delivery within 3-4 days.",
      "freeShippingValue" : {
        "currency" : "EUR",
        "amount" : 400
      },
      "fixedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 19.99
      },
      "weightBasedPrice" : null
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 3.192
    } ]
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "taxClass" : "REGULAR",
    "paymentMethod" : {
      "id" : "580f52d3-9d27-42c5-bc5c-25c084ed0f0a",
      "name" : "PayPal",
      "description" : "Pay by PayPal.",
      "discountOrFee" : {
        "type" : "ABSOLUTE",
        "absoluteValue" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 0
        },
        "percentageValue" : null
      },
      "onlinePayment" : false
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 0
    } ]
  },
  "customerEmail" : "a.alsterh@example.com",
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 68.2687
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 9.1713
  },
  "initialSubtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "initialGrandTotal" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "initialBalanceDue" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "initialNetTotal" : {
    "currency" : "EUR",
    "amount" : 68.2687
  },
  "initialTaxTotal" : {
    "currency" : "EUR",
    "amount" : 9.1713
  },
  "taxes" : [ {
    "taxClass" : "REGULAR",
    "taxRate" : 0.19,
    "currency" : "EUR",
    "amount" : 9.1713
  } ],
  "shippingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "Erdgeschoss",
    "addressExtension" : "Hinterhof",
    "postalCode" : "20999",
    "dependentLocality" : "Seevetal",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a.alsterh@example.com",
    "phone" : "(800) 555-0102",
    "mobile" : "(800) 555-0103",
    "doorCode" : "456",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "Erdgeschoss", "Hinterhof", "Seevetal", "20999 Alsterwasser", "GERMANY" ]
  },
  "billingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "Erdgeschoss",
    "addressExtension" : "Hinterhof",
    "postalCode" : "20999",
    "dependentLocality" : "Seevetal",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a.alsterh@example.com",
    "phone" : "(800) 555-0102",
    "mobile" : "(800) 555-0103",
    "vatId" : "DE123456789",
    "taxNumber" : "HRE 987654/32123/864516",
    "birthDate" : "1985-05-11",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "Erdgeschoss", "Hinterhof", "Seevetal", "20999 Alsterwasser", "GERMANY" ]
  },
  "paymentStatus" : "PENDING",
  "shippingStatus" : "UNSHIPPED",
  "canceled" : false,
  "orderNumber" : "10001",
  "customerComment" : "Please send with UPS.",
  "orderNote" : "Already paid.",
  "paymentNote" : "Reference EDB85BEA2DAE436E90C1E2027A0F012A",
  "externalPaymentId" : "6b2d2fg1-05c9-4159-146c-5fy2fe596z26",
  "externalPaymentUri" : "https://example.com/referral",
  "entryDate" : "2019-10-14T10:08:23.557",
  "totalReceived" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "totalRefunded" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "openAmount" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "marketingChannel" : "Google Shopping",
  "marketingSubchannel" : "Summer Sale",
  "salesChannel" : "Retail store",
  "backgroundJobs" : [ ],
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/e96b6bee-aef2-4ac1-941b-0bbe25af5346"
    },
    "order" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/e96b6bee-aef2-4ac1-941b-0bbe25af5346"
    },
    "order-note" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/e96b6bee-aef2-4ac1-941b-0bbe25af5346/order-note"
    },
    "processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/e96b6bee-aef2-4ac1-941b-0bbe25af5346/processes"
    },
    "events" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/e96b6bee-aef2-4ac1-941b-0bbe25af5346/events"
    },
    "cancel" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/e96b6bee-aef2-4ac1-941b-0bbe25af5346/cancel"
    },
    "create-invoice" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/e96b6bee-aef2-4ac1-941b-0bbe25af5346/create-invoice"
    },
    "terms-and-conditions-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/terms-and-conditions.pdf?hash=238734684735643875634578213"
    },
    "right-of-withdrawal-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/right-of-withdrawal.pdf?hash=647563475863487"
    }
  }
}

Show order number and order Id by cart Id

A GET request is used to retrieve the orderNumber and orderId of an order by cart ID. If no order is available for the given cart ID, an HTTP 404 - NOT FOUND response is returned.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/search/find-order-number-by-cart-id?cartId=1cbbd698-8582-4c06-a78f-eae6b76c843f' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json'

Response body properties

Path Type Description

orderId

String

The unique identifier of the order.

orderNumber

String

The automatically generated order number.

_links

Object

See Hypermedia

Links

Relation Description

order

The link to the order.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 211

{
  "orderId" : "98556a9e-0398-4c74-a45a-e483d334c3c9",
  "orderNumber" : "10001",
  "_links" : {
    "order" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/98556a9e-0398-4c74-a45a-e483d334c3c9"
    }
  }
}

Update order note

A PUT request is used to change the order note.

Required scopes

ordr:u

Request body properties

Path Type Description

orderNote

String

A merchant comment or note on the order.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/c818a4b3-79dd-4037-a920-dd7670df1145/order-note' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{
  "orderNote" : "not paid yet"
}'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 7745

{
  "cartId" : "c89a6034-6177-4793-81a2-fa525cd43615",
  "currency" : "EUR",
  "taxModel" : "GROSS",
  "taxable" : false,
  "testOrder" : false,
  "termsAndConditionsExplicitlyAccepted" : false,
  "productLineItems" : [ {
    "quantity" : 5,
    "initialQuantity" : 5,
    "unitPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 9.99
    },
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 49.95
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 49.95
    },
    "product" : {
      "_id" : "8708f081-0a52-43d7-9da0-f6d73fb3b5a9",
      "sku" : "EB001",
      "name" : "High Protein Power Bar (Pack of 5)",
      "essentialFeatures" : "Preservative-free. No added sweeteners. Vegan.",
      "shippingWeight" : 190,
      "defaultImageDataUri" : "http://your.image.hoster.com/randomimage.png",
      "variationAttributeValues" : [ {
        "displayName" : "flavor",
        "value" : "Salted Caramel"
      } ],
      "variationProductId" : "09bd2cae-7303-4b00-9547-1582223eb618"
    },
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 7.9743
    }
  }, {
    "quantity" : 3,
    "initialQuantity" : 3,
    "unitPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2.5
    },
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 7.5
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 7.5
    },
    "product" : {
      "_id" : "103078c8-5b8e-4153-86f9-daac6fbe82ba",
      "sku" : "sh-001",
      "name" : "Soft Walk Ultra - Nibok Men's",
      "essentialFeatures" : "Inner Material: Synthetic. Sole: Rubber. Upper Material: Leather.",
      "shippingWeight" : 190,
      "defaultImageDataUri" : "http://your.image.hoster.com/randomimage.png",
      "variationAttributeValues" : [ {
        "displayName" : "Size",
        "value" : "40 EU"
      } ],
      "variationProductId" : "fc707240-b899-41db-aa7a-3cfde5ccd39c"
    },
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 1.197
    }
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "taxClass" : "REGULAR",
    "shippingMethod" : {
      "id" : "f2be76a8-fbbc-4a4b-9955-b058483cadd7",
      "name" : "Standard",
      "description" : "Standard shipping. Delivery within 3-4 days.",
      "freeShippingValue" : {
        "currency" : "EUR",
        "amount" : 400
      },
      "fixedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 19.99
      },
      "weightBasedPrice" : null
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 3.192
    } ]
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "taxClass" : "REGULAR",
    "paymentMethod" : {
      "id" : "afcdd693-ff6b-4e35-bfc1-a1be60272071",
      "name" : "PayPal",
      "description" : "Pay by PayPal.",
      "discountOrFee" : {
        "type" : "ABSOLUTE",
        "absoluteValue" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 0
        },
        "percentageValue" : null
      },
      "onlinePayment" : false
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 0
    } ]
  },
  "customerEmail" : "a.alsterh@example.com",
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "initialSubtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "initialGrandTotal" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "initialBalanceDue" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 68.2687
  },
  "initialNetTotal" : {
    "currency" : "EUR",
    "amount" : 68.2687
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 9.1713
  },
  "initialTaxTotal" : {
    "currency" : "EUR",
    "amount" : 9.1713
  },
  "taxes" : [ {
    "taxClass" : "REGULAR",
    "taxRate" : 0.19,
    "currency" : "EUR",
    "amount" : 9.1713
  } ],
  "shippingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "Erdgeschoss",
    "addressExtension" : "Hinterhof",
    "postalCode" : "20999",
    "dependentLocality" : "Seevetal",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a.alsterh@example.com",
    "phone" : "(800) 555-0102",
    "mobile" : "(800) 555-0103",
    "doorCode" : "456",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "Erdgeschoss", "Hinterhof", "Seevetal", "20999 Alsterwasser", "GERMANY" ]
  },
  "billingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "Erdgeschoss",
    "addressExtension" : "Hinterhof",
    "postalCode" : "20999",
    "dependentLocality" : "Seevetal",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a.alsterh@example.com",
    "phone" : "(800) 555-0102",
    "mobile" : "(800) 555-0103",
    "vatId" : "DE123456789",
    "taxNumber" : "HRE 987654/32123/864516",
    "birthDate" : "1985-05-11",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "Erdgeschoss", "Hinterhof", "Seevetal", "20999 Alsterwasser", "GERMANY" ]
  },
  "orderNumber" : "10001",
  "invoiceNumber" : "",
  "previousInvoiceNumber" : null,
  "customerComment" : "Please send with UPS.",
  "orderNote" : "not paid yet",
  "paymentNote" : "Reference EDB85BEA2DAE436E90C1E2027A0F012A",
  "externalPaymentId" : "6b2d2fg1-05c9-4159-146c-5fy2fe596z26",
  "externalPaymentUri" : "https://example.com/referral",
  "invoicePdfUri" : null,
  "deliveryNotePdfUri" : null,
  "invoiceCorrectionPdfUris" : [ ],
  "invoiceCancelationPdfUris" : [ ],
  "entryDate" : "2019-10-14T10:08:40.853",
  "marketingChannel" : "Google Shopping",
  "marketingSubchannel" : "Summer Sale",
  "salesChannel" : "Retail store",
  "createdAt" : "2019-10-14T10:08:40.877",
  "shippingStatus" : "UNSHIPPED",
  "totalReceived" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "totalRefunded" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "openAmount" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "paymentStatus" : "PENDING",
  "canceled" : false,
  "_id" : "c818a4b3-79dd-4037-a920-dd7670df1145",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/c818a4b3-79dd-4037-a920-dd7670df1145"
    },
    "order" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/c818a4b3-79dd-4037-a920-dd7670df1145"
    }
  }
}

Update billing address

A PUT request is used to change the customer’s billing address.

Required scopes

ordr:u

Request body properties

Path Type Description Constraints

address

Object

The billing address of the cart. Refer to Set cart billing address for item documentation.

comment

String

Optional comment that describes the event.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/b048887a-71f2-4800-84db-0f39540356ee/billing-address' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{
  "address" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserstraße",
    "houseNumber" : "3",
    "street2" : "Erdgeschoss",
    "addressExtension" : "Hinterhof",
    "postalCode" : "20999",
    "dependentLocality" : "Seevetal",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a.alsterh@example.com",
    "phone" : "(800) 555-0102",
    "mobile" : "(800) 555-0103",
    "vatId" : "DE123456789",
    "taxNumber" : "HRE 987654/32123/864516",
    "birthDate" : "1985-05-11",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "Erdgeschoss", "Seevetal", "20999 Alsterwasser", "Germany" ],
    "_id" : null
  },
  "comment" : "Updated billing address"
}'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 10439

{
  "_id" : "b048887a-71f2-4800-84db-0f39540356ee",
  "createdAt" : "2019-10-14T10:08:25.976",
  "cartId" : "1252b682-3ba5-4cb2-8a34-269b91be242f",
  "currency" : "EUR",
  "taxModel" : "GROSS",
  "taxable" : false,
  "testOrder" : false,
  "termsAndConditionsExplicitlyAccepted" : false,
  "productLineItems" : [ {
    "_id" : "5612ebeb-d264-43da-8740-1ac4949f0440",
    "product" : {
      "_id" : "45130631-7eeb-405c-84ac-de6d46220b55",
      "sku" : "sh-001",
      "name" : "Soft Walk Ultra - Nibok Men's",
      "essentialFeatures" : "Inner Material: Synthetic. Sole: Rubber. Upper Material: Leather.",
      "shippingWeight" : 190,
      "defaultImageDataUri" : "http://your.image.hoster.com/randomimage.png",
      "variationAttributeValues" : [ {
        "displayName" : "Size",
        "value" : "40 EU"
      } ],
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/http:/your.image.hoster.com/randomimage.png"
        },
        "variation-product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/products/3bfffb54-9563-4f90-b44b-0e4b28adf687"
        }
      }
    },
    "quantity" : 3,
    "initialQuantity" : 3,
    "unitPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2.5
    },
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 7.5
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 7.5
    },
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 1.197
    },
    "unshipped" : {
      "quantity" : 3,
      "amount" : null
    },
    "shipped" : {
      "quantity" : 0,
      "amount" : null
    },
    "pending" : {
      "quantity" : 0,
      "amount" : null
    },
    "returned" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "broken" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "canceled" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    }
  }, {
    "_id" : "bbc9c8de-9355-4975-ad03-72beeeead64c",
    "product" : {
      "_id" : "878ab5b2-36a5-461f-a3b0-08150ce6bd19",
      "sku" : "EB001",
      "name" : "High Protein Power Bar (Pack of 5)",
      "essentialFeatures" : "Preservative-free. No added sweeteners. Vegan.",
      "shippingWeight" : 190,
      "defaultImageDataUri" : "http://your.image.hoster.com/randomimage.png",
      "variationAttributeValues" : [ {
        "displayName" : "flavor",
        "value" : "Salted Caramel"
      } ],
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/http:/your.image.hoster.com/randomimage.png"
        },
        "variation-product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/products/a5ddf6ab-343d-4b03-9111-8d20dd8db304"
        }
      }
    },
    "quantity" : 5,
    "initialQuantity" : 5,
    "unitPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 9.99
    },
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 49.95
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 49.95
    },
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 7.9743
    },
    "unshipped" : {
      "quantity" : 5,
      "amount" : null
    },
    "shipped" : {
      "quantity" : 0,
      "amount" : null
    },
    "pending" : {
      "quantity" : 0,
      "amount" : null
    },
    "returned" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "broken" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "canceled" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    }
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "taxClass" : "REGULAR",
    "shippingMethod" : {
      "id" : "b7b11911-e4fe-4705-be13-69fddf6ccdab",
      "name" : "Standard",
      "description" : "Standard shipping. Delivery within 3-4 days.",
      "freeShippingValue" : {
        "currency" : "EUR",
        "amount" : 400
      },
      "fixedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 19.99
      },
      "weightBasedPrice" : null
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 3.192
    } ]
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "taxClass" : "REGULAR",
    "paymentMethod" : {
      "id" : "0202c144-f022-4836-87ab-1626ed1fda80",
      "name" : "PayPal",
      "description" : "Pay by PayPal.",
      "discountOrFee" : {
        "type" : "ABSOLUTE",
        "absoluteValue" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 0
        },
        "percentageValue" : null
      },
      "onlinePayment" : false
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 0
    } ]
  },
  "customerEmail" : "a.alsterh@example.com",
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 68.2687
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 9.1713
  },
  "initialSubtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "initialGrandTotal" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "initialBalanceDue" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "initialNetTotal" : {
    "currency" : "EUR",
    "amount" : 68.2687
  },
  "initialTaxTotal" : {
    "currency" : "EUR",
    "amount" : 9.1713
  },
  "taxes" : [ {
    "taxClass" : "REGULAR",
    "taxRate" : 0.19,
    "currency" : "EUR",
    "amount" : 9.1713
  } ],
  "shippingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "Erdgeschoss",
    "addressExtension" : "Hinterhof",
    "postalCode" : "20999",
    "dependentLocality" : "Seevetal",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a.alsterh@example.com",
    "phone" : "(800) 555-0102",
    "mobile" : "(800) 555-0103",
    "doorCode" : "456",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "Erdgeschoss", "Hinterhof", "Seevetal", "20999 Alsterwasser", "GERMANY" ]
  },
  "billingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserstraße",
    "houseNumber" : "3",
    "street2" : "Erdgeschoss",
    "addressExtension" : "Hinterhof",
    "postalCode" : "20999",
    "dependentLocality" : "Seevetal",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a.alsterh@example.com",
    "phone" : "(800) 555-0102",
    "mobile" : "(800) 555-0103",
    "vatId" : "DE123456789",
    "taxNumber" : "HRE 987654/32123/864516",
    "birthDate" : "1985-05-11",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserstraße 3", "Erdgeschoss", "Hinterhof", "Seevetal", "20999 Alsterwasser", "GERMANY" ]
  },
  "paymentStatus" : "PENDING",
  "shippingStatus" : "UNSHIPPED",
  "canceled" : false,
  "orderNumber" : "10001",
  "customerComment" : "Please send with UPS.",
  "orderNote" : "Already paid.",
  "paymentNote" : "Reference EDB85BEA2DAE436E90C1E2027A0F012A",
  "externalPaymentId" : "6b2d2fg1-05c9-4159-146c-5fy2fe596z26",
  "externalPaymentUri" : "https://example.com/referral",
  "entryDate" : "2019-10-14T10:08:25.95",
  "totalReceived" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "totalRefunded" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "openAmount" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "marketingChannel" : "Google Shopping",
  "marketingSubchannel" : "Summer Sale",
  "salesChannel" : "Retail store",
  "backgroundJobs" : [ "render-invoice-correction-pdf" ],
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/b048887a-71f2-4800-84db-0f39540356ee"
    },
    "order" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/b048887a-71f2-4800-84db-0f39540356ee"
    },
    "order-note" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/b048887a-71f2-4800-84db-0f39540356ee/order-note"
    },
    "processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/b048887a-71f2-4800-84db-0f39540356ee/processes"
    },
    "events" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/b048887a-71f2-4800-84db-0f39540356ee/events"
    },
    "cancel" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/b048887a-71f2-4800-84db-0f39540356ee/cancel"
    },
    "invoice-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/pdf-storage/attachments/invoice-10003.pdf?hash=9e5e2631c6f5877d64cb3d40db46ec6eb48a3a92"
    },
    "send-invoice" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/b048887a-71f2-4800-84db-0f39540356ee/send-invoice"
    },
    "right-of-withdrawal-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/right-of-withdrawal.pdf?hash=647563475863487"
    },
    "terms-and-conditions-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/terms-and-conditions.pdf?hash=238734684735643875634578213"
    }
  }
}

Update shipping address

A PUT request is used to change the customer’s shipping address.

Required scopes

ordr:u

Request body properties

Path Type Description Constraints

address

Object

The shipping address of the cart. Defaults to billing address if no shipping address is set. Refer to Set cart shipping address for item documentation.

comment

String

Optional comment that describes the event.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/511ed03d-ae63-4d6d-a7f8-6fa534e72283/shipping-address' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{
  "address" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserstraße",
    "houseNumber" : "3",
    "street2" : "Erdgeschoss",
    "addressExtension" : "Hinterhof",
    "postalCode" : "20999",
    "dependentLocality" : "Seevetal",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a.alsterh@example.com",
    "phone" : "(800) 555-0102",
    "mobile" : "(800) 555-0103",
    "doorCode" : "456",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "Erdgeschoss", "Seevetal", "20999 Alsterwasser", "Germany" ],
    "_id" : null
  },
  "comment" : "Updated shipping address"
}'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 10249

{
  "_id" : "511ed03d-ae63-4d6d-a7f8-6fa534e72283",
  "createdAt" : "2019-10-14T10:08:30.427",
  "cartId" : "40fe53da-3414-47fe-a3e8-6b2018ec9fe3",
  "currency" : "EUR",
  "taxModel" : "GROSS",
  "taxable" : false,
  "testOrder" : false,
  "termsAndConditionsExplicitlyAccepted" : false,
  "productLineItems" : [ {
    "_id" : "9d3025d5-b5aa-4d88-9108-a65d6db24a68",
    "product" : {
      "_id" : "48814a7e-d5c3-4e2b-80bd-319b0c676774",
      "sku" : "EB001",
      "name" : "High Protein Power Bar (Pack of 5)",
      "essentialFeatures" : "Preservative-free. No added sweeteners. Vegan.",
      "shippingWeight" : 190,
      "defaultImageDataUri" : "http://your.image.hoster.com/randomimage.png",
      "variationAttributeValues" : [ {
        "displayName" : "flavor",
        "value" : "Salted Caramel"
      } ],
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/http:/your.image.hoster.com/randomimage.png"
        },
        "variation-product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/products/3d35fbfd-5b6f-49d1-8634-8ca688b3c352"
        }
      }
    },
    "quantity" : 5,
    "initialQuantity" : 5,
    "unitPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 9.99
    },
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 49.95
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 49.95
    },
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 7.9743
    },
    "unshipped" : {
      "quantity" : 5,
      "amount" : null
    },
    "shipped" : {
      "quantity" : 0,
      "amount" : null
    },
    "pending" : {
      "quantity" : 0,
      "amount" : null
    },
    "returned" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "broken" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "canceled" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    }
  }, {
    "_id" : "c35b5210-bffa-4f47-9d33-5d52ab3e083c",
    "product" : {
      "_id" : "075101d7-94a6-41f9-ba8b-dec5c944e06c",
      "sku" : "sh-001",
      "name" : "Soft Walk Ultra - Nibok Men's",
      "essentialFeatures" : "Inner Material: Synthetic. Sole: Rubber. Upper Material: Leather.",
      "shippingWeight" : 190,
      "defaultImageDataUri" : "http://your.image.hoster.com/randomimage.png",
      "variationAttributeValues" : [ {
        "displayName" : "Size",
        "value" : "40 EU"
      } ],
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/http:/your.image.hoster.com/randomimage.png"
        },
        "variation-product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/products/35dfb2ae-bafe-43fe-8c44-5e8c6aa38660"
        }
      }
    },
    "quantity" : 3,
    "initialQuantity" : 3,
    "unitPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2.5
    },
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 7.5
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 7.5
    },
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 1.197
    },
    "unshipped" : {
      "quantity" : 3,
      "amount" : null
    },
    "shipped" : {
      "quantity" : 0,
      "amount" : null
    },
    "pending" : {
      "quantity" : 0,
      "amount" : null
    },
    "returned" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "broken" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "canceled" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    }
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "taxClass" : "REGULAR",
    "shippingMethod" : {
      "id" : "b9943f4e-de1f-4ac9-a881-5f2092e5aa6e",
      "name" : "Standard",
      "description" : "Standard shipping. Delivery within 3-4 days.",
      "freeShippingValue" : {
        "currency" : "EUR",
        "amount" : 400
      },
      "fixedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 19.99
      },
      "weightBasedPrice" : null
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 3.192
    } ]
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "taxClass" : "REGULAR",
    "paymentMethod" : {
      "id" : "721523aa-91b7-4d1f-b262-f1009fdeec5a",
      "name" : "PayPal",
      "description" : "Pay by PayPal.",
      "discountOrFee" : {
        "type" : "ABSOLUTE",
        "absoluteValue" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 0
        },
        "percentageValue" : null
      },
      "onlinePayment" : false
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 0
    } ]
  },
  "customerEmail" : "a.alsterh@example.com",
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 68.2687
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 9.1713
  },
  "initialSubtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "initialGrandTotal" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "initialBalanceDue" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "initialNetTotal" : {
    "currency" : "EUR",
    "amount" : 68.2687
  },
  "initialTaxTotal" : {
    "currency" : "EUR",
    "amount" : 9.1713
  },
  "taxes" : [ {
    "taxClass" : "REGULAR",
    "taxRate" : 0.19,
    "currency" : "EUR",
    "amount" : 9.1713
  } ],
  "shippingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserstraße",
    "houseNumber" : "3",
    "street2" : "Erdgeschoss",
    "addressExtension" : "Hinterhof",
    "postalCode" : "20999",
    "dependentLocality" : "Seevetal",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a.alsterh@example.com",
    "phone" : "(800) 555-0102",
    "mobile" : "(800) 555-0103",
    "doorCode" : "456",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserstraße 3", "Erdgeschoss", "Hinterhof", "Seevetal", "20999 Alsterwasser", "GERMANY" ]
  },
  "billingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "Erdgeschoss",
    "addressExtension" : "Hinterhof",
    "postalCode" : "20999",
    "dependentLocality" : "Seevetal",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a.alsterh@example.com",
    "phone" : "(800) 555-0102",
    "mobile" : "(800) 555-0103",
    "vatId" : "DE123456789",
    "taxNumber" : "HRE 987654/32123/864516",
    "birthDate" : "1985-05-11",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "Erdgeschoss", "Hinterhof", "Seevetal", "20999 Alsterwasser", "GERMANY" ]
  },
  "paymentStatus" : "PENDING",
  "shippingStatus" : "UNSHIPPED",
  "canceled" : false,
  "orderNumber" : "10001",
  "customerComment" : "Please send with UPS.",
  "orderNote" : "Already paid.",
  "paymentNote" : "Reference EDB85BEA2DAE436E90C1E2027A0F012A",
  "externalPaymentId" : "6b2d2fg1-05c9-4159-146c-5fy2fe596z26",
  "externalPaymentUri" : "https://example.com/referral",
  "entryDate" : "2019-10-14T10:08:30.404",
  "totalReceived" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "totalRefunded" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "openAmount" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "marketingChannel" : "Google Shopping",
  "marketingSubchannel" : "Summer Sale",
  "salesChannel" : "Retail store",
  "backgroundJobs" : [ ],
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/511ed03d-ae63-4d6d-a7f8-6fa534e72283"
    },
    "order" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/511ed03d-ae63-4d6d-a7f8-6fa534e72283"
    },
    "order-note" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/511ed03d-ae63-4d6d-a7f8-6fa534e72283/order-note"
    },
    "processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/511ed03d-ae63-4d6d-a7f8-6fa534e72283/processes"
    },
    "events" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/511ed03d-ae63-4d6d-a7f8-6fa534e72283/events"
    },
    "cancel" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/511ed03d-ae63-4d6d-a7f8-6fa534e72283/cancel"
    },
    "create-invoice" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/511ed03d-ae63-4d6d-a7f8-6fa534e72283/create-invoice"
    },
    "right-of-withdrawal-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/right-of-withdrawal.pdf?hash=647563475863487"
    },
    "terms-and-conditions-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/terms-and-conditions.pdf?hash=238734684735643875634578213"
    }
  }
}

Create invoice

A POST request is used to create an invoice for the order.

Required scopes

ordr:u

Request body properties

Path Type Description Constraints

deliveryDateNote

String

The delivery date note defined by the merchant to be printed on the invoice.

Length must be between 0 and 500 inclusive

invoiceNote

String

The invoice note defined by the merchant to be printed on the invoice.

Length must be between 0 and 500 inclusive

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/7a224f55-254d-4687-a1ae-ea4b43a735ed/create-invoice' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{"deliveryDateNote": "Test DeliveryDateNote", "invoiceNote": "Test invoiceNote"}'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 10268

{
  "_id" : "7a224f55-254d-4687-a1ae-ea4b43a735ed",
  "createdAt" : "2019-10-14T10:08:39.714",
  "cartId" : "a05f7778-a57a-4f94-a79d-78fc545afd02",
  "currency" : "EUR",
  "taxModel" : "GROSS",
  "taxable" : false,
  "testOrder" : false,
  "termsAndConditionsExplicitlyAccepted" : false,
  "productLineItems" : [ {
    "_id" : "706eb081-35fe-404e-a065-35e401f6402d",
    "product" : {
      "_id" : "25aaafab-dabb-48dd-a5e0-51b89779b6f7",
      "sku" : "sh-001",
      "name" : "Soft Walk Ultra - Nibok Men's",
      "essentialFeatures" : "Inner Material: Synthetic. Sole: Rubber. Upper Material: Leather.",
      "shippingWeight" : 190,
      "defaultImageDataUri" : "http://your.image.hoster.com/randomimage.png",
      "variationAttributeValues" : [ {
        "displayName" : "Size",
        "value" : "40 EU"
      } ],
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/http:/your.image.hoster.com/randomimage.png"
        },
        "variation-product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/products/28047598-d4e8-47b3-abe7-b0c6708a17ae"
        }
      }
    },
    "quantity" : 3,
    "initialQuantity" : 3,
    "unitPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2.5
    },
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 7.5
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 7.5
    },
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 1.197
    },
    "unshipped" : {
      "quantity" : 3,
      "amount" : null
    },
    "shipped" : {
      "quantity" : 0,
      "amount" : null
    },
    "pending" : {
      "quantity" : 0,
      "amount" : null
    },
    "returned" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "broken" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "canceled" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    }
  }, {
    "_id" : "dd42b106-9c42-4fef-9cc1-e9c0191e4fb4",
    "product" : {
      "_id" : "0c4bb445-b2cc-4e5c-aad2-a20b6fc4e25e",
      "sku" : "EB001",
      "name" : "High Protein Power Bar (Pack of 5)",
      "essentialFeatures" : "Preservative-free. No added sweeteners. Vegan.",
      "shippingWeight" : 190,
      "defaultImageDataUri" : "http://your.image.hoster.com/randomimage.png",
      "variationAttributeValues" : [ {
        "displayName" : "flavor",
        "value" : "Salted Caramel"
      } ],
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/http:/your.image.hoster.com/randomimage.png"
        },
        "variation-product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/products/5a635231-68d8-46fc-b661-1759f20d0adc"
        }
      }
    },
    "quantity" : 5,
    "initialQuantity" : 5,
    "unitPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 9.99
    },
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 49.95
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 49.95
    },
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 7.9743
    },
    "unshipped" : {
      "quantity" : 5,
      "amount" : null
    },
    "shipped" : {
      "quantity" : 0,
      "amount" : null
    },
    "pending" : {
      "quantity" : 0,
      "amount" : null
    },
    "returned" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "broken" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "canceled" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    }
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "taxClass" : "REGULAR",
    "shippingMethod" : {
      "id" : "f30abac2-d794-4851-afcc-7637657fc56d",
      "name" : "Standard",
      "description" : "Standard shipping. Delivery within 3-4 days.",
      "freeShippingValue" : {
        "currency" : "EUR",
        "amount" : 400
      },
      "fixedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 19.99
      },
      "weightBasedPrice" : null
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 3.192
    } ]
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "taxClass" : "REGULAR",
    "paymentMethod" : {
      "id" : "44149714-176c-4af0-9f1c-3dbd901d0264",
      "name" : "PayPal",
      "description" : "Pay by PayPal.",
      "discountOrFee" : {
        "type" : "ABSOLUTE",
        "absoluteValue" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 0
        },
        "percentageValue" : null
      },
      "onlinePayment" : false
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 0
    } ]
  },
  "customerEmail" : "a.alsterh@example.com",
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 68.2687
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 9.1713
  },
  "initialSubtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "initialGrandTotal" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "initialBalanceDue" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "initialNetTotal" : {
    "currency" : "EUR",
    "amount" : 68.2687
  },
  "initialTaxTotal" : {
    "currency" : "EUR",
    "amount" : 9.1713
  },
  "taxes" : [ {
    "taxClass" : "REGULAR",
    "taxRate" : 0.19,
    "currency" : "EUR",
    "amount" : 9.1713
  } ],
  "shippingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "Erdgeschoss",
    "addressExtension" : "Hinterhof",
    "postalCode" : "20999",
    "dependentLocality" : "Seevetal",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a.alsterh@example.com",
    "phone" : "(800) 555-0102",
    "mobile" : "(800) 555-0103",
    "doorCode" : "456",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "Erdgeschoss", "Hinterhof", "Seevetal", "20999 Alsterwasser", "GERMANY" ]
  },
  "billingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "Erdgeschoss",
    "addressExtension" : "Hinterhof",
    "postalCode" : "20999",
    "dependentLocality" : "Seevetal",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a.alsterh@example.com",
    "phone" : "(800) 555-0102",
    "mobile" : "(800) 555-0103",
    "vatId" : "DE123456789",
    "taxNumber" : "HRE 987654/32123/864516",
    "birthDate" : "1985-05-11",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "Erdgeschoss", "Hinterhof", "Seevetal", "20999 Alsterwasser", "GERMANY" ]
  },
  "paymentStatus" : "PENDING",
  "shippingStatus" : "UNSHIPPED",
  "canceled" : false,
  "orderNumber" : "10001",
  "customerComment" : "Please send with UPS.",
  "orderNote" : "Already paid.",
  "paymentNote" : "Reference EDB85BEA2DAE436E90C1E2027A0F012A",
  "externalPaymentId" : "6b2d2fg1-05c9-4159-146c-5fy2fe596z26",
  "externalPaymentUri" : "https://example.com/referral",
  "entryDate" : "2019-10-14T10:08:39.671",
  "totalReceived" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "totalRefunded" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "openAmount" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "marketingChannel" : "Google Shopping",
  "marketingSubchannel" : "Summer Sale",
  "salesChannel" : "Retail store",
  "backgroundJobs" : [ "render-invoice-pdf" ],
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/7a224f55-254d-4687-a1ae-ea4b43a735ed"
    },
    "order" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/7a224f55-254d-4687-a1ae-ea4b43a735ed"
    },
    "order-note" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/7a224f55-254d-4687-a1ae-ea4b43a735ed/order-note"
    },
    "processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/7a224f55-254d-4687-a1ae-ea4b43a735ed/processes"
    },
    "events" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/7a224f55-254d-4687-a1ae-ea4b43a735ed/events"
    },
    "cancel" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/7a224f55-254d-4687-a1ae-ea4b43a735ed/cancel"
    },
    "retry-create-invoice" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/7a224f55-254d-4687-a1ae-ea4b43a735ed/create-invoice"
    },
    "right-of-withdrawal-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/right-of-withdrawal.pdf?hash=647563475863487"
    },
    "terms-and-conditions-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/terms-and-conditions.pdf?hash=238734684735643875634578213"
    }
  }
}

Send invoice

A POST request is used to send an invoice for the order.

Required scopes

ordr:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/4bb313b3-671a-43eb-8954-b46b082a552d/send-invoice' -i -X POST \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 10400

{
  "_id" : "4bb313b3-671a-43eb-8954-b46b082a552d",
  "createdAt" : "2019-10-14T10:08:33.494",
  "cartId" : "b6a8f0ab-f63f-45da-8c2f-224df4895484",
  "currency" : "EUR",
  "taxModel" : "GROSS",
  "taxable" : false,
  "testOrder" : false,
  "termsAndConditionsExplicitlyAccepted" : false,
  "productLineItems" : [ {
    "_id" : "f02c5c9b-1a7f-48aa-bcd6-44afe2b0d740",
    "product" : {
      "_id" : "4135eb1e-77aa-4cc8-9829-5cc300d6a66d",
      "sku" : "EB001",
      "name" : "High Protein Power Bar (Pack of 5)",
      "essentialFeatures" : "Preservative-free. No added sweeteners. Vegan.",
      "shippingWeight" : 190,
      "defaultImageDataUri" : "http://your.image.hoster.com/randomimage.png",
      "variationAttributeValues" : [ {
        "displayName" : "flavor",
        "value" : "Salted Caramel"
      } ],
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/http:/your.image.hoster.com/randomimage.png"
        },
        "variation-product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/products/ae3feb22-1c8a-4607-a8f2-e14535e26c3a"
        }
      }
    },
    "quantity" : 5,
    "initialQuantity" : 5,
    "unitPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 9.99
    },
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 49.95
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 49.95
    },
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 7.9743
    },
    "unshipped" : {
      "quantity" : 5,
      "amount" : null
    },
    "shipped" : {
      "quantity" : 0,
      "amount" : null
    },
    "pending" : {
      "quantity" : 0,
      "amount" : null
    },
    "returned" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "broken" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "canceled" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    }
  }, {
    "_id" : "facb3386-3683-4b4d-b5dd-5be105f5b8db",
    "product" : {
      "_id" : "3fa24daf-ab5a-48f6-87b2-5f82cf166219",
      "sku" : "sh-001",
      "name" : "Soft Walk Ultra - Nibok Men's",
      "essentialFeatures" : "Inner Material: Synthetic. Sole: Rubber. Upper Material: Leather.",
      "shippingWeight" : 190,
      "defaultImageDataUri" : "http://your.image.hoster.com/randomimage.png",
      "variationAttributeValues" : [ {
        "displayName" : "Size",
        "value" : "40 EU"
      } ],
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/http:/your.image.hoster.com/randomimage.png"
        },
        "variation-product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/products/5aa80ab7-5d12-4e0d-a5ed-943565c721b9"
        }
      }
    },
    "quantity" : 3,
    "initialQuantity" : 3,
    "unitPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2.5
    },
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 7.5
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 7.5
    },
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 1.197
    },
    "unshipped" : {
      "quantity" : 3,
      "amount" : null
    },
    "shipped" : {
      "quantity" : 0,
      "amount" : null
    },
    "pending" : {
      "quantity" : 0,
      "amount" : null
    },
    "returned" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "broken" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "canceled" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    }
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "taxClass" : "REGULAR",
    "shippingMethod" : {
      "id" : "ca1519ed-21e1-4b4d-abbd-1dc90165b81e",
      "name" : "Standard",
      "description" : "Standard shipping. Delivery within 3-4 days.",
      "freeShippingValue" : {
        "currency" : "EUR",
        "amount" : 400
      },
      "fixedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 19.99
      },
      "weightBasedPrice" : null
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 3.192
    } ]
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "taxClass" : "REGULAR",
    "paymentMethod" : {
      "id" : "e14485a9-fbee-443d-aa1c-e62e446359a8",
      "name" : "PayPal",
      "description" : "Pay by PayPal.",
      "discountOrFee" : {
        "type" : "ABSOLUTE",
        "absoluteValue" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 0
        },
        "percentageValue" : null
      },
      "onlinePayment" : false
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 0
    } ]
  },
  "customerEmail" : "a.alsterh@example.com",
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 68.2687
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 9.1713
  },
  "initialSubtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "initialGrandTotal" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "initialBalanceDue" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "initialNetTotal" : {
    "currency" : "EUR",
    "amount" : 68.2687
  },
  "initialTaxTotal" : {
    "currency" : "EUR",
    "amount" : 9.1713
  },
  "taxes" : [ {
    "taxClass" : "REGULAR",
    "taxRate" : 0.19,
    "currency" : "EUR",
    "amount" : 9.1713
  } ],
  "shippingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "Erdgeschoss",
    "addressExtension" : "Hinterhof",
    "postalCode" : "20999",
    "dependentLocality" : "Seevetal",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a.alsterh@example.com",
    "phone" : "(800) 555-0102",
    "mobile" : "(800) 555-0103",
    "doorCode" : "456",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "Erdgeschoss", "Hinterhof", "Seevetal", "20999 Alsterwasser", "GERMANY" ]
  },
  "billingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "Erdgeschoss",
    "addressExtension" : "Hinterhof",
    "postalCode" : "20999",
    "dependentLocality" : "Seevetal",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a.alsterh@example.com",
    "phone" : "(800) 555-0102",
    "mobile" : "(800) 555-0103",
    "vatId" : "DE123456789",
    "taxNumber" : "HRE 987654/32123/864516",
    "birthDate" : "1985-05-11",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "Erdgeschoss", "Hinterhof", "Seevetal", "20999 Alsterwasser", "GERMANY" ]
  },
  "paymentStatus" : "PENDING",
  "shippingStatus" : "UNSHIPPED",
  "canceled" : false,
  "orderNumber" : "10001",
  "customerComment" : "Please send with UPS.",
  "orderNote" : "Already paid.",
  "paymentNote" : "Reference EDB85BEA2DAE436E90C1E2027A0F012A",
  "externalPaymentId" : "6b2d2fg1-05c9-4159-146c-5fy2fe596z26",
  "externalPaymentUri" : "https://example.com/referral",
  "entryDate" : "2019-10-14T10:08:33.471",
  "totalReceived" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "totalRefunded" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "openAmount" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "marketingChannel" : "Google Shopping",
  "marketingSubchannel" : "Summer Sale",
  "salesChannel" : "Retail store",
  "backgroundJobs" : [ ],
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/4bb313b3-671a-43eb-8954-b46b082a552d"
    },
    "order" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/4bb313b3-671a-43eb-8954-b46b082a552d"
    },
    "order-note" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/4bb313b3-671a-43eb-8954-b46b082a552d/order-note"
    },
    "processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/4bb313b3-671a-43eb-8954-b46b082a552d/processes"
    },
    "events" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/4bb313b3-671a-43eb-8954-b46b082a552d/events"
    },
    "cancel" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/4bb313b3-671a-43eb-8954-b46b082a552d/cancel"
    },
    "invoice-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/pdf-storage/attachments/invoice-10003.pdf?hash=9e5e2631c6f5877d64cb3d40db46ec6eb48a3a92"
    },
    "send-invoice" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/4bb313b3-671a-43eb-8954-b46b082a552d/send-invoice"
    },
    "right-of-withdrawal-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/right-of-withdrawal.pdf?hash=647563475863487"
    },
    "terms-and-conditions-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/terms-and-conditions.pdf?hash=238734684735643875634578213"
    }
  }
}

List order processes

A GET request is used to list all order processes.

Required scopes

ordp:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/f3988773-20d9-4de6-9a56-992f26b610e5/processes' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_embedded.payment-processes

Array

All payment processes of the order.

_embedded.shipping-processes

Array

All shipping processes of the order.

_embedded.return-processes

Array

All return processes of the order.

_embedded.cancel-processes

Array

All cancelation processes of the order.

_embedded.refund-processes

Array

All refund processes of the order.

_links

Object

See Hypermedia

Links

Relation Description

processes

The link to order processes.

shipping-processes

The link to all shipping processes of the order.

payment-processes

The link to all payment processes of the order.

return-processes

The link to all return processes of the order.

cancel-processes

The link to all cancelation processes of the order.

refund-processes

The link to all refund processes of the order.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 5287

{
  "_embedded" : {
    "refund-processes" : [ {
      "amount" : {
        "currency" : "EUR",
        "amount" : 19.98
      },
      "status" : "VOIDED",
      "completed" : true,
      "_id" : "10e6333f-12a0-4234-b411-f9cf027debd2",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/f3988773-20d9-4de6-9a56-992f26b610e5/processes/refunds/10e6333f-12a0-4234-b411-f9cf027debd2"
        },
        "refund-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/f3988773-20d9-4de6-9a56-992f26b610e5/processes/refunds/10e6333f-12a0-4234-b411-f9cf027debd2"
        }
      }
    }, {
      "amount" : {
        "currency" : "EUR",
        "amount" : 39.96
      },
      "status" : "PENDING",
      "completed" : false,
      "_id" : "8c574856-4384-4c55-8b1f-80c0faa0ec27",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/f3988773-20d9-4de6-9a56-992f26b610e5/processes/refunds/8c574856-4384-4c55-8b1f-80c0faa0ec27"
        },
        "refund-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/f3988773-20d9-4de6-9a56-992f26b610e5/processes/refunds/8c574856-4384-4c55-8b1f-80c0faa0ec27"
        },
        "mark-paid" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/f3988773-20d9-4de6-9a56-992f26b610e5/processes/refunds/8c574856-4384-4c55-8b1f-80c0faa0ec27/mark-paid"
        }
      }
    } ],
    "cancel-processes" : [ {
      "lineItems" : [ {
        "productLineItemId" : "61e63f16-98fc-41f2-ae2f-2f2182ab9334",
        "quantity" : 2
      } ],
      "_id" : "ef51e1ab-23f5-44c3-af9e-29003c74da56",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/f3988773-20d9-4de6-9a56-992f26b610e5/processes/cancelations/ef51e1ab-23f5-44c3-af9e-29003c74da56"
        },
        "cancel-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/f3988773-20d9-4de6-9a56-992f26b610e5/processes/cancelations/ef51e1ab-23f5-44c3-af9e-29003c74da56"
        }
      }
    } ],
    "shipping-processes" : [ {
      "status" : "SHIPPED",
      "trackingCode" : "LZ101003859US",
      "trackingLink" : "http://example.com/track?code=LZ101003859US",
      "lineItems" : [ {
        "productLineItemId" : "61e63f16-98fc-41f2-ae2f-2f2182ab9334",
        "quantity" : 3
      } ],
      "_id" : "c0090712-b783-4f62-8d1a-e206004fd493",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/f3988773-20d9-4de6-9a56-992f26b610e5/processes/shippings/c0090712-b783-4f62-8d1a-e206004fd493"
        },
        "shipping-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/f3988773-20d9-4de6-9a56-992f26b610e5/processes/shippings/c0090712-b783-4f62-8d1a-e206004fd493"
        },
        "mark-delivered" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/f3988773-20d9-4de6-9a56-992f26b610e5/processes/shippings/c0090712-b783-4f62-8d1a-e206004fd493/mark-delivered"
        }
      }
    } ],
    "payment-processes" : [ {
      "amount" : {
        "currency" : "EUR",
        "amount" : 77.44
      },
      "status" : "PAID",
      "paymentId" : null,
      "captureWorkflow" : null,
      "completed" : true,
      "_id" : "8c8e31b0-cad2-40ff-973a-87722fab0a42",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/f3988773-20d9-4de6-9a56-992f26b610e5/processes/payments/8c8e31b0-cad2-40ff-973a-87722fab0a42"
        },
        "payment-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/f3988773-20d9-4de6-9a56-992f26b610e5/processes/payments/8c8e31b0-cad2-40ff-973a-87722fab0a42"
        }
      }
    } ],
    "return-processes" : [ {
      "lineItems" : [ {
        "productLineItemId" : "61e63f16-98fc-41f2-ae2f-2f2182ab9334",
        "quantity" : 2,
        "status" : "RETURNED"
      } ],
      "shippingPriceRefund" : null,
      "_id" : "d34f8362-9757-4054-89ae-f8b5d1abe169",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/f3988773-20d9-4de6-9a56-992f26b610e5/processes/returns/d34f8362-9757-4054-89ae-f8b5d1abe169"
        },
        "return-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/f3988773-20d9-4de6-9a56-992f26b610e5/processes/returns/d34f8362-9757-4054-89ae-f8b5d1abe169"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/f3988773-20d9-4de6-9a56-992f26b610e5/processes"
    },
    "processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/f3988773-20d9-4de6-9a56-992f26b610e5/processes"
    },
    "payment-processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/f3988773-20d9-4de6-9a56-992f26b610e5/processes/payments"
    },
    "shipping-processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/f3988773-20d9-4de6-9a56-992f26b610e5/processes/shippings"
    },
    "return-processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/f3988773-20d9-4de6-9a56-992f26b610e5/processes/returns"
    },
    "cancel-processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/f3988773-20d9-4de6-9a56-992f26b610e5/processes/cancelations"
    },
    "refund-processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/f3988773-20d9-4de6-9a56-992f26b610e5/processes/refunds"
    }
  }
}

List payment processes

A GET request is used to list all payment processes of an order in a paged way.

Required scopes

pypr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/32f5b70c-15b3-485e-8ba5-04be38673a1c/processes/payments?page=0&size=20' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_links

Object

See Hypermedia

_embedded.payment-processes[].completed

Boolean

Indicates if the payment has been completed. Can be true or false.

_embedded.payment-processes[].status

String

The status of the payment process. Can be PARTIALLY_PAID, REFUNDED, PENDING, APPROVED, CAPTURE_PENDING, PAID, VOIDED, FAILED, or EXECUTED.

_embedded.payment-processes[].captureWorkflow

Null

Indicates how and when to capture an authorized payment. Can be one of CAPTURE_ON_ORDER or CAPTURE_ON_DEMAND.

_embedded.payment-processes[].amount.amount

Number

The amount due for this payment process.

_embedded.payment-processes[].amount.currency

String

The currency of the amount due in this payment process.

_embedded.payment-processes[]._id

String

The ID of the payment process.

_embedded.payment-processes[].paymentId

Null

The ID of the payment created by the payment gateway.

page

Object

See Pagination

Links

Relation Description

payment-processes

The link to all payment processes of the order.

active

The link to the active payment process of the order.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1622

{
  "_embedded" : {
    "payment-processes" : [ {
      "amount" : {
        "currency" : "EUR",
        "amount" : 77.44
      },
      "status" : "PENDING",
      "paymentId" : null,
      "captureWorkflow" : null,
      "completed" : false,
      "_id" : "ba0044ee-3cd3-4dd4-a01c-03fff2b69b32",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/32f5b70c-15b3-485e-8ba5-04be38673a1c/processes/payments/ba0044ee-3cd3-4dd4-a01c-03fff2b69b32"
        },
        "payment-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/32f5b70c-15b3-485e-8ba5-04be38673a1c/processes/payments/ba0044ee-3cd3-4dd4-a01c-03fff2b69b32"
        },
        "mark-voided" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/32f5b70c-15b3-485e-8ba5-04be38673a1c/processes/payments/ba0044ee-3cd3-4dd4-a01c-03fff2b69b32/mark-voided"
        },
        "mark-paid" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/32f5b70c-15b3-485e-8ba5-04be38673a1c/processes/payments/ba0044ee-3cd3-4dd4-a01c-03fff2b69b32/mark-paid"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/32f5b70c-15b3-485e-8ba5-04be38673a1c/processes/payments?page=0&size=20"
    },
    "payment-processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/32f5b70c-15b3-485e-8ba5-04be38673a1c/processes/payments"
    },
    "active" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/32f5b70c-15b3-485e-8ba5-04be38673a1c/processes/payments/active"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

Show payment process details

A GET request is used to retrieve the payment processes.

Required scopes

pypr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/940b73b2-8eb6-440a-ae60-471cbe9dff30/processes/payments/d6d04148-72d4-46ce-b75b-28ffd6729184' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

completed

Boolean

Indicates if the payment has been completed. Can be true or false.

status

String

The status of the payment process. Can be PARTIALLY_PAID, REFUNDED, PENDING, APPROVED, CAPTURE_PENDING, PAID, VOIDED, FAILED, or EXECUTED.

captureWorkflow

Null

Indicates how and when to capture an authorized payment. Can be one of CAPTURE_ON_ORDER or CAPTURE_ON_DEMAND.

amount.amount

Number

The amount due for this payment process.

amount.currency

String

The currency of the amount due in this payment process.

_id

String

The ID of the payment process.

paymentId

Null

The ID of the payment created by the payment gateway.

_links

Object

See Hypermedia

Links

Relation Description

payment-process

The link to the current payment process.

mark-paid

The link to set the current payment process to paid.

mark-voided

The link to set the current payment process to voided.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 934

{
  "amount" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "status" : "PENDING",
  "paymentId" : null,
  "captureWorkflow" : null,
  "completed" : false,
  "_id" : "d6d04148-72d4-46ce-b75b-28ffd6729184",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/940b73b2-8eb6-440a-ae60-471cbe9dff30/processes/payments/d6d04148-72d4-46ce-b75b-28ffd6729184"
    },
    "payment-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/940b73b2-8eb6-440a-ae60-471cbe9dff30/processes/payments/d6d04148-72d4-46ce-b75b-28ffd6729184"
    },
    "mark-voided" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/940b73b2-8eb6-440a-ae60-471cbe9dff30/processes/payments/d6d04148-72d4-46ce-b75b-28ffd6729184/mark-voided"
    },
    "mark-paid" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/940b73b2-8eb6-440a-ae60-471cbe9dff30/processes/payments/d6d04148-72d4-46ce-b75b-28ffd6729184/mark-paid"
    }
  }
}

Show online payment process details

A GET request is used to retrieve the online payment processes.

Required scopes

pypr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/85fb77c9-a482-4a96-8872-28d19a8129f0/processes/payments/fae1361f-d60c-473b-b75b-1c59c813014b' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

completed

Boolean

Indicates if the payment has been completed. Can be true or false.

status

String

The status of the payment process. Can be PARTIALLY_PAID, REFUNDED, PENDING, APPROVED, CAPTURE_PENDING, PAID, VOIDED, FAILED, or EXECUTED.

captureWorkflow

String

Indicates how and when to capture an authorized payment. Can be one of CAPTURE_ON_ORDER or CAPTURE_ON_DEMAND.

amount.amount

Number

The amount due for this payment process.

amount.currency

String

The currency of the amount due in this payment process.

_id

String

The ID of the payment process.

paymentId

String

The ID of the payment created by the payment gateway.

_links

Object

See Hypermedia

Links

Relation Description

payment-process

The link to the current payment process.

capture

The link to manually capture the current payment process.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 797

{
  "amount" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "status" : "APPROVED",
  "paymentId" : "bce49976-6dc7-4977-a4f4-e59303036147",
  "captureWorkflow" : "CAPTURE_ON_DEMAND",
  "completed" : false,
  "_id" : "fae1361f-d60c-473b-b75b-1c59c813014b",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/85fb77c9-a482-4a96-8872-28d19a8129f0/processes/payments/fae1361f-d60c-473b-b75b-1c59c813014b"
    },
    "payment-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/85fb77c9-a482-4a96-8872-28d19a8129f0/processes/payments/fae1361f-d60c-473b-b75b-1c59c813014b"
    },
    "capture" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/85fb77c9-a482-4a96-8872-28d19a8129f0/processes/payments/fae1361f-d60c-473b-b75b-1c59c813014b/capture"
    }
  }
}

Show active payment process details

A GET request is used to retrieve the active payment processes. There is only one active payment process. See Show payment process details for more information about the request and response structure.

Required scopes

pypr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/634c95bb-3d0a-4d75-9622-fbaffaa93109/processes/payments/active' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 934

{
  "amount" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "status" : "PENDING",
  "paymentId" : null,
  "captureWorkflow" : null,
  "completed" : false,
  "_id" : "02cfb609-6cc3-4899-8c0e-d50bb4e789b8",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/634c95bb-3d0a-4d75-9622-fbaffaa93109/processes/payments/02cfb609-6cc3-4899-8c0e-d50bb4e789b8"
    },
    "payment-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/634c95bb-3d0a-4d75-9622-fbaffaa93109/processes/payments/02cfb609-6cc3-4899-8c0e-d50bb4e789b8"
    },
    "mark-voided" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/634c95bb-3d0a-4d75-9622-fbaffaa93109/processes/payments/02cfb609-6cc3-4899-8c0e-d50bb4e789b8/mark-voided"
    },
    "mark-paid" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/634c95bb-3d0a-4d75-9622-fbaffaa93109/processes/payments/02cfb609-6cc3-4899-8c0e-d50bb4e789b8/mark-paid"
    }
  }
}

Mark payment process as voided

A POST request is used to mark the payment process as voided.

Required scopes

pypr:u

Request body properties

Path Type Description

comment

String

The comment to this status change.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/703464f2-06c3-48f3-9e59-7c98a29c397f/processes/payments/129a7531-d4f9-4c16-bb87-165cf2ffc12b/mark-voided' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{
  "comment" : "comment"
}'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 570

{
  "amount" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "status" : "VOIDED",
  "paymentId" : null,
  "captureWorkflow" : null,
  "completed" : true,
  "_id" : "129a7531-d4f9-4c16-bb87-165cf2ffc12b",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/703464f2-06c3-48f3-9e59-7c98a29c397f/processes/payments/129a7531-d4f9-4c16-bb87-165cf2ffc12b"
    },
    "payment-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/703464f2-06c3-48f3-9e59-7c98a29c397f/processes/payments/129a7531-d4f9-4c16-bb87-165cf2ffc12b"
    }
  }
}

Mark payment process as paid

A POST request is used to mark the payment process as paid.

Required scopes

pypr:u

Request body properties

Path Type Description

comment

String

The comment to this status change.

details.amount.amount

Number

The amount paid.

details.amount.currency

String

The currency of the amount paid.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/91a14510-34eb-4e76-a9a8-52d3a1c9ea6c/processes/payments/14595521-0b90-4be5-a193-ec7101c9d288/mark-paid' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{
  "comment" : "comment",
  "details" : {
    "amount" : {
      "currency" : "EUR",
      "amount" : 77.44
    }
  }
}'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 568

{
  "amount" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "status" : "PAID",
  "paymentId" : null,
  "captureWorkflow" : null,
  "completed" : true,
  "_id" : "14595521-0b90-4be5-a193-ec7101c9d288",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/91a14510-34eb-4e76-a9a8-52d3a1c9ea6c/processes/payments/14595521-0b90-4be5-a193-ec7101c9d288"
    },
    "payment-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/91a14510-34eb-4e76-a9a8-52d3a1c9ea6c/processes/payments/14595521-0b90-4be5-a193-ec7101c9d288"
    }
  }
}

Capture payment

A POST request is used to capture the payment.

Required scopes

pypr:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/82dc1b7c-d9b1-4325-a319-1c1256a69a0a/processes/payments/67bf2736-53ed-435e-9b0f-b06b1763ca4b/capture' -i -X POST \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

completed

Boolean

Indicates if the payment has been completed. Can be true or false.

status

String

The status of the payment process. Can be PARTIALLY_PAID, REFUNDED, PENDING, APPROVED, CAPTURE_PENDING, PAID, VOIDED, FAILED, or EXECUTED.

captureWorkflow

String

Indicates how and when to capture an authorized payment. Can be one of CAPTURE_ON_ORDER or CAPTURE_ON_DEMAND.

amount.amount

Number

The amount due for this payment process.

amount.currency

String

The currency of the amount due in this payment process.

_id

String

The ID of the payment process.

paymentId

String

The ID of the payment created by the payment gateway.

_links

Object

See Hypermedia

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 617

{
  "amount" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "status" : "PAID",
  "paymentId" : "074c64b0-2782-4489-af4c-1d9645551e6e",
  "captureWorkflow" : "CAPTURE_ON_DEMAND",
  "completed" : true,
  "_id" : "67bf2736-53ed-435e-9b0f-b06b1763ca4b",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/82dc1b7c-d9b1-4325-a319-1c1256a69a0a/processes/payments/67bf2736-53ed-435e-9b0f-b06b1763ca4b"
    },
    "payment-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/82dc1b7c-d9b1-4325-a319-1c1256a69a0a/processes/payments/67bf2736-53ed-435e-9b0f-b06b1763ca4b"
    }
  }
}

List refund processes

A GET request is used to list all refund processes of an order in a paged way. Refunds are triggered if either a cancelation or return process is created. See Create cancelation processes and Create return processes for more information.

Required scopes

rfpr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/2a8814ac-7452-43b7-bca7-6daf64ac7214/processes/refunds?page=0&size=20' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_links

Object

See Hypermedia

_embedded.refund-processes[].completed

Boolean

Indicates if the refund has been completed. Can be true or false.

_embedded.refund-processes[].status

String

The status of the refund process. Can be PENDING, PAID, or VOIDED.

_embedded.refund-processes[].amount.amount

Number

The amount due for this refund process.

_embedded.refund-processes[].amount.currency

String

The currency of the amount due in this refund process.

_embedded.refund-processes[]._id

String

The ID of the refund process.

page

Object

See Pagination

Links

Relation Description

refund-processes

The link to all refund processes of the order.

active

The link to the active payment process of the order.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1360

{
  "_embedded" : {
    "refund-processes" : [ {
      "amount" : {
        "currency" : "EUR",
        "amount" : 19.98
      },
      "status" : "PENDING",
      "completed" : false,
      "_id" : "a67c951c-8601-44ea-b797-4d19b26c346d",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/2a8814ac-7452-43b7-bca7-6daf64ac7214/processes/refunds/a67c951c-8601-44ea-b797-4d19b26c346d"
        },
        "refund-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/2a8814ac-7452-43b7-bca7-6daf64ac7214/processes/refunds/a67c951c-8601-44ea-b797-4d19b26c346d"
        },
        "mark-paid" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/2a8814ac-7452-43b7-bca7-6daf64ac7214/processes/refunds/a67c951c-8601-44ea-b797-4d19b26c346d/mark-paid"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/2a8814ac-7452-43b7-bca7-6daf64ac7214/processes/refunds?page=0&size=20"
    },
    "refund-processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/2a8814ac-7452-43b7-bca7-6daf64ac7214/processes/refunds"
    },
    "active" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/2a8814ac-7452-43b7-bca7-6daf64ac7214/processes/refunds/active"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

Show refund process details

A GET request is used to retrieve the refund processes.

Required scopes

rfpr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/7951b5a8-876e-4b5a-ae9d-f64a29103b2c/processes/refunds/03139576-e3e9-44e5-94b4-8c618ee0599b' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

completed

Boolean

Indicates if the refund has been completed. Can be true or false.

status

String

The status of the refund process. Can be PENDING, PAID, or VOIDED.

amount.amount

Number

The amount due for this refund process.

amount.currency

String

The currency of the amount due in this refund process.

_id

String

The ID of the refund process.

_links

Object

See Hypermedia

Links

Relation Description

refund-process

The link to the current refund process.

mark-paid

The link to set the current payment process to paid.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 697

{
  "amount" : {
    "currency" : "EUR",
    "amount" : 19.98
  },
  "status" : "PENDING",
  "completed" : false,
  "_id" : "03139576-e3e9-44e5-94b4-8c618ee0599b",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/7951b5a8-876e-4b5a-ae9d-f64a29103b2c/processes/refunds/03139576-e3e9-44e5-94b4-8c618ee0599b"
    },
    "refund-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/7951b5a8-876e-4b5a-ae9d-f64a29103b2c/processes/refunds/03139576-e3e9-44e5-94b4-8c618ee0599b"
    },
    "mark-paid" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/7951b5a8-876e-4b5a-ae9d-f64a29103b2c/processes/refunds/03139576-e3e9-44e5-94b4-8c618ee0599b/mark-paid"
    }
  }
}

Show active refund process details

A GET request is used to retrieve the active refund processes. There is only one active refund process. See Show refund process details for more information about the request and response structure.

Required scopes

rfpr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/d475f833-bc4a-4d8e-a78d-73bcef313533/processes/refunds/active' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 697

{
  "amount" : {
    "currency" : "EUR",
    "amount" : 19.98
  },
  "status" : "PENDING",
  "completed" : false,
  "_id" : "66057c3b-c6cb-45cb-8c11-db92d1a6d692",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/d475f833-bc4a-4d8e-a78d-73bcef313533/processes/refunds/66057c3b-c6cb-45cb-8c11-db92d1a6d692"
    },
    "refund-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/d475f833-bc4a-4d8e-a78d-73bcef313533/processes/refunds/66057c3b-c6cb-45cb-8c11-db92d1a6d692"
    },
    "mark-paid" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/d475f833-bc4a-4d8e-a78d-73bcef313533/processes/refunds/66057c3b-c6cb-45cb-8c11-db92d1a6d692/mark-paid"
    }
  }
}

Mark refund process as paid

A POST request is used to mark the refund process as paid.

Required scopes

rfpr:u

Request body properties

Path Type Description

comment

String

The comment to this status change.

details.amount.amount

Number

The amount refunded.

details.amount.currency

String

The currency of the amount refunded.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/11c12aa1-d199-4f42-92e3-ae1a0a7b781c/processes/refunds/active/mark-paid' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{
  "comment" : "comment",
  "details" : {
    "amount" : {
      "currency" : "EUR",
      "amount" : 19.98
    }
  }
}'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 515

{
  "amount" : {
    "currency" : "EUR",
    "amount" : 19.98
  },
  "status" : "PAID",
  "completed" : true,
  "_id" : "a26c51c5-830b-4fe2-8ebe-ddb0b0a41dc3",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/11c12aa1-d199-4f42-92e3-ae1a0a7b781c/processes/refunds/a26c51c5-830b-4fe2-8ebe-ddb0b0a41dc3"
    },
    "refund-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/11c12aa1-d199-4f42-92e3-ae1a0a7b781c/processes/refunds/a26c51c5-830b-4fe2-8ebe-ddb0b0a41dc3"
    }
  }
}

List shipping processes

A GET request is used to list all shipping processes of an order in a paged way.

Required scopes

shpr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/79190a3b-d208-4e00-8432-c31bacbf26d6/processes/shippings?page=0&size=20' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_links

Object

See Hypermedia

_embedded.shipping-processes[].lineItems

Array

The line items that are included in this shipping process.

_embedded.shipping-processes[].status

String

The status of the shipping process. Can be UNSHIPPED, PARTIALLY_SHIPPED, or SHIPPED.

_embedded.shipping-processes[].trackingCode

String

The tracking code for this shipping process.

_embedded.shipping-processes[].trackingLink

String

The tracking link for this shipping process.

_embedded.shipping-processes[]._id

String

The ID of the shipping process.

page

Object

See Pagination

Links

Relation Description

shipping-processes

The link to all shipping processes of the order.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1579

{
  "_embedded" : {
    "shipping-processes" : [ {
      "status" : "PENDING",
      "trackingCode" : "LZ101003859US",
      "trackingLink" : "http://example.com/track?code=LZ101003859US",
      "lineItems" : [ {
        "productLineItemId" : "ab5e3b33-5367-439f-ac0a-34bae395ab41",
        "quantity" : 3
      } ],
      "_id" : "8275a836-95f0-46b4-b198-afaa491cf4b1",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/79190a3b-d208-4e00-8432-c31bacbf26d6/processes/shippings/8275a836-95f0-46b4-b198-afaa491cf4b1"
        },
        "shipping-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/79190a3b-d208-4e00-8432-c31bacbf26d6/processes/shippings/8275a836-95f0-46b4-b198-afaa491cf4b1"
        },
        "mark-shipped" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/79190a3b-d208-4e00-8432-c31bacbf26d6/processes/shippings/8275a836-95f0-46b4-b198-afaa491cf4b1/mark-shipped"
        },
        "mark-delivered" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/79190a3b-d208-4e00-8432-c31bacbf26d6/processes/shippings/8275a836-95f0-46b4-b198-afaa491cf4b1/mark-delivered"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/79190a3b-d208-4e00-8432-c31bacbf26d6/processes/shippings?page=0&size=20"
    },
    "shipping-processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/79190a3b-d208-4e00-8432-c31bacbf26d6/processes/shippings"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

Show shipping process details

A GET request is used to retrieve the shipping process details.

Required scopes

shpr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/dd94f310-65c4-4104-aa1b-759df39dfcdf/processes/shippings/df8a0715-01c5-475b-a10f-6b72d94e00dd' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

lineItems

Array

The line items that are included in this shipping process.

status

String

The status of the shipping process. Can be UNSHIPPED, PARTIALLY_SHIPPED, or SHIPPED.

trackingCode

String

The tracking code for this shipping process.

trackingLink

String

The tracking link for this shipping process.

_id

String

The ID of the shipping process.

_links

Object

See Hypermedia

Links

Relation Description

shipping-process

The link to the current shipping process.

mark-shipped

The link to set the current shipping process to shipped.

mark-delivered

The link to set the current shipping process to delivered.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1027

{
  "status" : "PENDING",
  "trackingCode" : "LZ101003859US",
  "trackingLink" : "http://example.com/track?code=LZ101003859US",
  "lineItems" : [ {
    "productLineItemId" : "f0cc6ace-71c6-4851-8bba-7e6e5a7857e9",
    "quantity" : 3
  } ],
  "_id" : "df8a0715-01c5-475b-a10f-6b72d94e00dd",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/dd94f310-65c4-4104-aa1b-759df39dfcdf/processes/shippings/df8a0715-01c5-475b-a10f-6b72d94e00dd"
    },
    "shipping-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/dd94f310-65c4-4104-aa1b-759df39dfcdf/processes/shippings/df8a0715-01c5-475b-a10f-6b72d94e00dd"
    },
    "mark-shipped" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/dd94f310-65c4-4104-aa1b-759df39dfcdf/processes/shippings/df8a0715-01c5-475b-a10f-6b72d94e00dd/mark-shipped"
    },
    "mark-delivered" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/dd94f310-65c4-4104-aa1b-759df39dfcdf/processes/shippings/df8a0715-01c5-475b-a10f-6b72d94e00dd/mark-delivered"
    }
  }
}

Create shipping processes

A POST request is ussed to create a new shipping processes for an order.

Required scopes

shpr:c

Request body properties

Path Type Description

comment

String

The comment to this status change.

sendMail

Boolean

Indicates if an email is to be sent out to the customer to indicate the shipping process transition.

createDeliveryNote

Boolean

Indicates if a packing slip pdf will be created as part of shipping process.

trackingCode

String

The tracking code for this shipping process.

trackingLink

String

The tracking link for this shipping process.

lineItems[].productLineItemId

String

The ID of a product line item that is marked with a new status.

lineItems[].quantity

Number

The quantity of a product line item that is marked with a new status.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/6b6a037b-a6b7-4556-9a32-b1433149359e/processes/shippings' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{
  "comment" : "This needs to be done fast!",
  "sendMail" : true,
  "createDeliveryNote" : true,
  "trackingCode" : "LZ101003859US",
  "trackingLink" : "http://example.com/track?code=LZ101003859US",
  "lineItems" : [ {
    "quantity" : 3,
    "productLineItemId" : "662ff6e6-7dc4-4537-8b99-aeff678b5d68"
  } ]
}'

Example response

HTTP/1.1 201 Created
Location: https://api-shop.beyondshop.cloud/api/orders/6b6a037b-a6b7-4556-9a32-b1433149359e/processes/shippings/f9fcc120-6e83-4e56-9b28-d8630857ce9a
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1027

{
  "status" : "PENDING",
  "trackingCode" : "LZ101003859US",
  "trackingLink" : "http://example.com/track?code=LZ101003859US",
  "lineItems" : [ {
    "productLineItemId" : "662ff6e6-7dc4-4537-8b99-aeff678b5d68",
    "quantity" : 3
  } ],
  "_id" : "f9fcc120-6e83-4e56-9b28-d8630857ce9a",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/6b6a037b-a6b7-4556-9a32-b1433149359e/processes/shippings/f9fcc120-6e83-4e56-9b28-d8630857ce9a"
    },
    "shipping-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/6b6a037b-a6b7-4556-9a32-b1433149359e/processes/shippings/f9fcc120-6e83-4e56-9b28-d8630857ce9a"
    },
    "mark-shipped" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/6b6a037b-a6b7-4556-9a32-b1433149359e/processes/shippings/f9fcc120-6e83-4e56-9b28-d8630857ce9a/mark-shipped"
    },
    "mark-delivered" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/6b6a037b-a6b7-4556-9a32-b1433149359e/processes/shippings/f9fcc120-6e83-4e56-9b28-d8630857ce9a/mark-delivered"
    }
  }
}

Mark shipment as shipped

A POST request is used to mark the shipment as shipped.

Required scopes

shpr:u

Request body properties

Path Type Description

comment

String

The comment to this status change.

sendMail

Boolean

Indicates if an email is to be sent out to the customer to indicate the shipping process transition.

details.trackingCode

String

The tracking code for this shipping process.

details.trackingLink

String

The tracking link for this shipping process.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/38db24ae-3f03-42e0-82a9-5dfde27a8bc5/processes/shippings/7008a7e2-0682-4bef-8c05-5d011f9b88de/mark-shipped' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{
  "comment" : "This needs to be done fast!",
  "sendMail" : true,
  "details" : {
    "trackingCode" : "LZ101003859US",
    "trackingLink" : "http://example.com/track?code=LZ101003859US"
  }
}'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 841

{
  "status" : "SHIPPED",
  "trackingCode" : "LZ101003859US",
  "trackingLink" : "http://example.com/track?code=LZ101003859US",
  "lineItems" : [ {
    "productLineItemId" : "72b5876d-9627-4add-9dd2-e89408de7401",
    "quantity" : 3
  } ],
  "_id" : "7008a7e2-0682-4bef-8c05-5d011f9b88de",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/38db24ae-3f03-42e0-82a9-5dfde27a8bc5/processes/shippings/7008a7e2-0682-4bef-8c05-5d011f9b88de"
    },
    "shipping-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/38db24ae-3f03-42e0-82a9-5dfde27a8bc5/processes/shippings/7008a7e2-0682-4bef-8c05-5d011f9b88de"
    },
    "mark-delivered" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/38db24ae-3f03-42e0-82a9-5dfde27a8bc5/processes/shippings/7008a7e2-0682-4bef-8c05-5d011f9b88de/mark-delivered"
    }
  }
}

Mark shipment as delivered

A POST request is used to mark the shipment as delivered.

Required scopes

shpr:u

Request body properties

Path Type Description

comment

String

The comment to this status change.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/a7a73572-0974-441c-a97a-03bdb8a52f3e/processes/shippings/736698c9-9d0f-47c2-9463-9cb2c1f0f078/mark-delivered' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{
  "comment" : "comment"
}'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 653

{
  "status" : "DELIVERED",
  "trackingCode" : "LZ101003859US",
  "trackingLink" : "http://example.com/track?code=LZ101003859US",
  "lineItems" : [ {
    "productLineItemId" : "eb623c57-013d-4767-8ef6-98ce50fea7b2",
    "quantity" : 3
  } ],
  "_id" : "736698c9-9d0f-47c2-9463-9cb2c1f0f078",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/a7a73572-0974-441c-a97a-03bdb8a52f3e/processes/shippings/736698c9-9d0f-47c2-9463-9cb2c1f0f078"
    },
    "shipping-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/a7a73572-0974-441c-a97a-03bdb8a52f3e/processes/shippings/736698c9-9d0f-47c2-9463-9cb2c1f0f078"
    }
  }
}

List return processes

A GET request is used to list all return processes of an order in a paged way.

Required scopes

rtpr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/b88c2c88-c3e6-4e63-92d4-8b4191312666/processes/returns?page=0&size=20' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_links

Object

See Hypermedia

_embedded.return-processes[].lineItems

Array

The product line items that are included in this return process.

_embedded.return-processes[]._id

String

The ID of the return process.

_embedded.return-processes[].shippingPriceRefund.currency

String

The currency of the price for the shipping line item.

_embedded.return-processes[].shippingPriceRefund.amount

Number

The price for the shipping line item to be refunded.

page

Object

See Pagination

Links

Relation Description

return-processes

The link to all return processes of the order.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1152

{
  "_embedded" : {
    "return-processes" : [ {
      "lineItems" : [ {
        "productLineItemId" : "5ebe5e7f-c83d-4160-9912-7394e0314855",
        "quantity" : 3,
        "status" : "RETURNED"
      } ],
      "shippingPriceRefund" : {
        "currency" : "EUR",
        "amount" : 19.99
      },
      "_id" : "1cbf6c82-aa7d-4b99-b403-fb9dad9c5a6b",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/b88c2c88-c3e6-4e63-92d4-8b4191312666/processes/returns/1cbf6c82-aa7d-4b99-b403-fb9dad9c5a6b"
        },
        "return-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/b88c2c88-c3e6-4e63-92d4-8b4191312666/processes/returns/1cbf6c82-aa7d-4b99-b403-fb9dad9c5a6b"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/b88c2c88-c3e6-4e63-92d4-8b4191312666/processes/returns?page=0&size=20"
    },
    "return-processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/b88c2c88-c3e6-4e63-92d4-8b4191312666/processes/returns"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

Show return process details

A GET request is used to retrieve the return process details.

Required scopes

rtpr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/93f5d90e-b2df-4d5a-9492-2018d3b228f2/processes/returns/c0e6faa4-14da-4779-a61f-25689d6547fd' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

lineItems

Array

The product line items that are included in this return process.

_id

String

The ID of the return process.

shippingPriceRefund.currency

String

The currency of the price for the shipping line item.

shippingPriceRefund.amount

Number

The price for the shipping line item to be refunded.

_links

Object

See Hypermedia

Links

Relation Description

return-process

The link to the current return process.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 624

{
  "lineItems" : [ {
    "productLineItemId" : "bd7ad84e-6314-4798-b4e9-8ea0739e060d",
    "quantity" : 3,
    "status" : "RETURNED"
  } ],
  "shippingPriceRefund" : {
    "currency" : "EUR",
    "amount" : 19.99
  },
  "_id" : "c0e6faa4-14da-4779-a61f-25689d6547fd",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/93f5d90e-b2df-4d5a-9492-2018d3b228f2/processes/returns/c0e6faa4-14da-4779-a61f-25689d6547fd"
    },
    "return-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/93f5d90e-b2df-4d5a-9492-2018d3b228f2/processes/returns/c0e6faa4-14da-4779-a61f-25689d6547fd"
    }
  }
}

Create return processes

A POST request is used to create a new return process for an order. Return processes trigger a refund process.

Required scopes

rtpr:c

Request body properties

Path Type Description

comment

String

The comment to this status change.

sendMail

Boolean

Indicates if an email is sent out to the customer to indicate that the merchant received the returned items. Can be true or false.

lineItems[].productLineItemId

String

The ID of a specified product line item in this return process.

lineItems[].quantity

Number

The quantity of the product line item in this return process.

shippingPriceRefund.currency

String

The currency of the price for the shipping line item.

shippingPriceRefund.amount

Number

The price for the shipping line item to be refunded.

lineItems[].status

String

The status of the product line item in this return process. Can be RETURNED or BROKEN.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/99d454fe-6b55-48ea-8013-bd131f0e223d/processes/returns' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{
  "comment" : "This needs to be done fast!",
  "sendMail" : true,
  "lineItems" : [ {
    "quantity" : 3,
    "productLineItemId" : "30cb7ca9-5b88-42cd-8a54-edbea66bf665",
    "status" : "RETURNED"
  } ],
  "shippingPriceRefund" : {
    "currency" : "EUR",
    "amount" : 19.99
  }
}'

Example response

HTTP/1.1 201 Created
Location: https://api-shop.beyondshop.cloud/api/orders/99d454fe-6b55-48ea-8013-bd131f0e223d/processes/returns/990228de-f53d-4c80-8d7f-ed2843dd7be7
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 624

{
  "lineItems" : [ {
    "productLineItemId" : "30cb7ca9-5b88-42cd-8a54-edbea66bf665",
    "quantity" : 3,
    "status" : "RETURNED"
  } ],
  "shippingPriceRefund" : {
    "currency" : "EUR",
    "amount" : 19.99
  },
  "_id" : "990228de-f53d-4c80-8d7f-ed2843dd7be7",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/99d454fe-6b55-48ea-8013-bd131f0e223d/processes/returns/990228de-f53d-4c80-8d7f-ed2843dd7be7"
    },
    "return-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/99d454fe-6b55-48ea-8013-bd131f0e223d/processes/returns/990228de-f53d-4c80-8d7f-ed2843dd7be7"
    }
  }
}

List cancelation processes

A GET request is used to list all cancelation processes of an order in a paged way.

Required scopes

clpr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/bf9f3ece-7552-4b65-a6dd-939be2e38015/processes/cancelations?page=0&size=20' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_links

Object

See Hypermedia

_embedded.cancel-processes[].lineItems

Array

The product line items that are included in this cancelation process.

_embedded.cancel-processes[]._id

String

The ID of the cancelation process.

page

Object

See Pagination

Links

Relation Description

cancel-processes

The link to all cancelation processes of the order.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1047

{
  "_embedded" : {
    "cancel-processes" : [ {
      "lineItems" : [ {
        "productLineItemId" : "3cf7cea2-1c37-4811-84b9-80ff9b08b292",
        "quantity" : 3
      } ],
      "_id" : "a80f0c71-b095-4686-a449-bb16e7a6f79f",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/bf9f3ece-7552-4b65-a6dd-939be2e38015/processes/cancelations/a80f0c71-b095-4686-a449-bb16e7a6f79f"
        },
        "cancel-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/bf9f3ece-7552-4b65-a6dd-939be2e38015/processes/cancelations/a80f0c71-b095-4686-a449-bb16e7a6f79f"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/bf9f3ece-7552-4b65-a6dd-939be2e38015/processes/cancelations?page=0&size=20"
    },
    "cancel-processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/bf9f3ece-7552-4b65-a6dd-939be2e38015/processes/cancelations"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

Show cancelation process details

A GET request is used to retrieve the cancelation process details of an order.

Required scopes

clpr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/ee707828-6f60-4e21-826d-3434c6cd4286/processes/cancelations/6a6cfad4-1090-445f-ae4a-5619f65bcb52' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

lineItems

Array

The product line items that are included in this cancelation process.

_id

String

The ID of the cancelation process.

_links

Object

See Hypermedia

Links

Relation Description

cancel-process

The link to the current cancelation process.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 529

{
  "lineItems" : [ {
    "productLineItemId" : "9cbc819f-bcfc-4e9a-a963-63de232334b0",
    "quantity" : 3
  } ],
  "_id" : "6a6cfad4-1090-445f-ae4a-5619f65bcb52",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/ee707828-6f60-4e21-826d-3434c6cd4286/processes/cancelations/6a6cfad4-1090-445f-ae4a-5619f65bcb52"
    },
    "cancel-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/ee707828-6f60-4e21-826d-3434c6cd4286/processes/cancelations/6a6cfad4-1090-445f-ae4a-5619f65bcb52"
    }
  }
}

Create cancelation processes

A POST request is used to create a new cancelation process for an order. Cancelation processes trigger a refund process.

Required scopes

clpr:c

Request body properties

Path Type Description

comment

String

The comment to this status change.

lineItems[].productLineItemId

String

The ID of a specified product line item in this cancelation process.

lineItems[].quantity

Number

The quantity of the product line item in this cancelation process.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/f5e9ee3d-9f10-4665-863d-72538e699039/processes/cancelations' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{"comment":"This needs to be done fast!","lineItems":[{"quantity":3,"productLineItemId":"85ac2a7d-dfce-490b-9b4d-2ead15eeeb72"}]}'

Example response

HTTP/1.1 201 Created
Location: https://api-shop.beyondshop.cloud/api/orders/f5e9ee3d-9f10-4665-863d-72538e699039/processes/cancelations/487f9fc4-ac7d-451c-aa98-c7a2d48a7fad
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 529

{
  "lineItems" : [ {
    "productLineItemId" : "85ac2a7d-dfce-490b-9b4d-2ead15eeeb72",
    "quantity" : 3
  } ],
  "_id" : "487f9fc4-ac7d-451c-aa98-c7a2d48a7fad",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/f5e9ee3d-9f10-4665-863d-72538e699039/processes/cancelations/487f9fc4-ac7d-451c-aa98-c7a2d48a7fad"
    },
    "cancel-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/f5e9ee3d-9f10-4665-863d-72538e699039/processes/cancelations/487f9fc4-ac7d-451c-aa98-c7a2d48a7fad"
    }
  }
}

Cancel order

A POST request is used to cancel an order.

Required scopes

clpr:c

Request body properties

Path Type Description

comment

String

The comment to this status change.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/f1c36e6f-a12f-4086-95a0-92c76c2d6230/cancel' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{"comment":"This needs to be done fast!"}'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 10250

{
  "_id" : "f1c36e6f-a12f-4086-95a0-92c76c2d6230",
  "createdAt" : "2019-10-14T10:07:19.343",
  "cartId" : "ecf49301-2f9b-461c-aac7-79c2c0c35f1e",
  "currency" : "EUR",
  "taxModel" : "GROSS",
  "taxable" : true,
  "testOrder" : false,
  "termsAndConditionsExplicitlyAccepted" : false,
  "productLineItems" : [ {
    "_id" : "42884cf8-09c7-4e95-8d86-ba44c2d25773",
    "product" : {
      "_id" : "0775a9c3-f8f0-4800-8ac1-901887efcb29",
      "sku" : "sh-001",
      "name" : "Soft Walk Ultra - Nibok Men's",
      "essentialFeatures" : "Inner Material: Synthetic. Sole: Rubber. Upper Material: Leather.",
      "shippingWeight" : 190,
      "defaultImageDataUri" : "http://your.image.hoster.com/randomimage.png",
      "variationAttributeValues" : [ {
        "displayName" : "Size",
        "value" : "40 EU"
      } ],
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/http:/your.image.hoster.com/randomimage.png"
        },
        "variation-product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/products/1df592a6-897c-42a6-bec6-10c2e4f3b5c4"
        }
      }
    },
    "quantity" : 0,
    "initialQuantity" : 3,
    "unitPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2.5
    },
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 7.5
    },
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 0
    },
    "unshipped" : {
      "quantity" : 0,
      "amount" : null
    },
    "shipped" : {
      "quantity" : 0,
      "amount" : null
    },
    "pending" : {
      "quantity" : 0,
      "amount" : null
    },
    "returned" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "broken" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "canceled" : {
      "quantity" : 3,
      "amount" : {
        "currency" : "EUR",
        "amount" : 7.5
      }
    }
  }, {
    "_id" : "6c53c0cd-4a88-4aec-918a-56db6d24c2e0",
    "product" : {
      "_id" : "61e330bd-efb9-445c-a1dc-d463b18b7ab5",
      "sku" : "EB001",
      "name" : "High Protein Power Bar (Pack of 5)",
      "essentialFeatures" : "Preservative-free. No added sweeteners. Vegan.",
      "shippingWeight" : 190,
      "defaultImageDataUri" : "http://your.image.hoster.com/randomimage.png",
      "variationAttributeValues" : [ {
        "displayName" : "flavor",
        "value" : "Salted Caramel"
      } ],
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/http:/your.image.hoster.com/randomimage.png"
        },
        "variation-product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/products/6cd8cdbf-ccb6-4642-a39e-05de0fa91a02"
        }
      }
    },
    "quantity" : 0,
    "initialQuantity" : 5,
    "unitPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 9.99
    },
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 49.95
    },
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 0
    },
    "unshipped" : {
      "quantity" : 0,
      "amount" : null
    },
    "shipped" : {
      "quantity" : 0,
      "amount" : null
    },
    "pending" : {
      "quantity" : 0,
      "amount" : null
    },
    "returned" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "broken" : {
      "quantity" : 0,
      "amount" : {
        "currency" : "EUR",
        "amount" : 0
      }
    },
    "canceled" : {
      "quantity" : 5,
      "amount" : {
        "currency" : "EUR",
        "amount" : 49.95
      }
    }
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "taxClass" : "REGULAR",
    "shippingMethod" : {
      "id" : "14246311-a707-4b41-a77f-6babb48ac8c3",
      "name" : "Standard",
      "description" : "Standard shipping. Delivery within 3-4 days.",
      "freeShippingValue" : {
        "currency" : "EUR",
        "amount" : 400
      },
      "fixedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 19.99
      },
      "weightBasedPrice" : null
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.0,
      "currency" : "EUR",
      "amount" : 0
    } ]
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "taxClass" : "REGULAR",
    "paymentMethod" : {
      "id" : "341e710d-28a6-43f5-91d4-efb9cbe323b0",
      "name" : "PayPal",
      "description" : "Pay by PayPal.",
      "discountOrFee" : {
        "type" : "ABSOLUTE",
        "absoluteValue" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 0
        },
        "percentageValue" : null
      },
      "onlinePayment" : false
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.0,
      "currency" : "EUR",
      "amount" : 0
    } ]
  },
  "customerEmail" : "a.alsterh@example.com",
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "initialSubtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "initialGrandTotal" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "initialBalanceDue" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "initialNetTotal" : {
    "currency" : "EUR",
    "amount" : 68.2687
  },
  "initialTaxTotal" : {
    "currency" : "EUR",
    "amount" : 9.1713
  },
  "taxes" : [ {
    "taxClass" : "REGULAR",
    "taxRate" : 0.0,
    "currency" : "EUR",
    "amount" : 1
  } ],
  "shippingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "Erdgeschoss",
    "addressExtension" : "Hinterhof",
    "postalCode" : "20999",
    "dependentLocality" : "Seevetal",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a.alsterh@example.com",
    "phone" : "(800) 555-0102",
    "mobile" : "(800) 555-0103",
    "doorCode" : "456",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "Erdgeschoss", "Hinterhof", "Seevetal", "20999 Alsterwasser", "GERMANY" ]
  },
  "billingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "Erdgeschoss",
    "addressExtension" : "Hinterhof",
    "postalCode" : "20999",
    "dependentLocality" : "Seevetal",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a.alsterh@example.com",
    "phone" : "(800) 555-0102",
    "mobile" : "(800) 555-0103",
    "vatId" : "DE123456789",
    "taxNumber" : "HRE 987654/32123/864516",
    "birthDate" : "1985-05-11",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "Erdgeschoss", "Hinterhof", "Seevetal", "20999 Alsterwasser", "GERMANY" ]
  },
  "paymentStatus" : "REFUND_PENDING",
  "shippingStatus" : "SHIPPED",
  "canceled" : true,
  "orderNumber" : "10001",
  "customerComment" : "Please send with UPS.",
  "orderNote" : "Already paid.",
  "paymentNote" : "Reference EDB85BEA2DAE436E90C1E2027A0F012A",
  "externalPaymentId" : "6b2d2fg1-05c9-4159-146c-5fy2fe596z26",
  "externalPaymentUri" : "https://example.com/referral",
  "entryDate" : "2019-10-14T10:07:19.321",
  "totalReceived" : {
    "currency" : "EUR",
    "amount" : 77.44
  },
  "totalRefunded" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "openAmount" : {
    "currency" : "EUR",
    "amount" : -77.44
  },
  "marketingChannel" : "Google Shopping",
  "marketingSubchannel" : "Summer Sale",
  "salesChannel" : "Retail store",
  "backgroundJobs" : [ "render-invoice-cancelation-pdf" ],
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/f1c36e6f-a12f-4086-95a0-92c76c2d6230"
    },
    "order" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/f1c36e6f-a12f-4086-95a0-92c76c2d6230"
    },
    "order-note" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/f1c36e6f-a12f-4086-95a0-92c76c2d6230/order-note"
    },
    "processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/f1c36e6f-a12f-4086-95a0-92c76c2d6230/processes"
    },
    "events" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/f1c36e6f-a12f-4086-95a0-92c76c2d6230/events"
    },
    "invoice-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/http:/pdf-storage/invoice-1000.pdf?hash=2387463287462348762348732"
    },
    "send-invoice" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/f1c36e6f-a12f-4086-95a0-92c76c2d6230/send-invoice"
    },
    "right-of-withdrawal-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/right-of-withdrawal.pdf?hash=647563475863487"
    },
    "terms-and-conditions-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/terms-and-conditions.pdf?hash=238734684735643875634578213"
    }
  }
}

List order events

A GET request is used to list all events of an order in a paged way.

Required scopes

orde:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/114f787b-2d0a-4e4d-91a8-06e47a20a7b4/events' -i -X GET \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_embedded.order-events[].triggeredBy

String

The user or client that triggered the order event.

_embedded.order-events[].comment

String

Optional comment that describes the event.

_embedded.order-events[].createdAt

String

The date and time the order event was created. According to ISO 8601.

_embedded.order-events[].details.type

String

The type of the order event. Can be order-created, order-shipped, items-returned, items-canceled, order-canceled, payment-created, payment-voided, payment-capture-pending, payment-paid, payment-executed, payment-failed, payment-execution-temporarily-failed, invoice-created, invoice-sent, invoice-correction-created, invoice-cancelation-created, delivery-note-created, order-shipping-address-changed, order-billing-address-changed, shipping-shipped, shipping-delivered, shipping-pending, refund-created, refund-voided, refund-paid, refund-failed, or refund-not-supported.

_embedded.order-events[].details.previousInvoiceNumber

String

The invoice number before invoice correction.

_embedded.order-events[].details.newInvoiceNumber

String

The new invoice number after invoice correction.

_embedded.order-events[].details.invoiceNumber

String

The invoice number of an invoice.

_embedded.order-events[]._links.payment-process.href

String

The link to the corresponding payment process.

_links

Object

See Hypermedia

page

Object

See Pagination

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 3518

{
  "_embedded" : {
    "order-events" : [ {
      "triggeredBy" : null,
      "comment" : null,
      "createdAt" : "2019-10-14T10:03:06.555",
      "details" : {
        "invoicePdfUri" : "/api/pdf-storage/attachments/invoice-10003.pdf?hash=9e5e2631c6f5877d64cb3d40db46ec6eb48a3a92",
        "previousInvoiceNumber" : "10001",
        "newInvoiceNumber" : "10002",
        "type" : "invoice-correction-created"
      }
    }, {
      "triggeredBy" : "user",
      "comment" : "changed street",
      "createdAt" : "2019-10-14T10:03:06.278",
      "details" : {
        "type" : "order-billing-address-changed"
      }
    }, {
      "triggeredBy" : null,
      "comment" : null,
      "createdAt" : "2019-10-14T10:03:06.025",
      "details" : {
        "invoicePdfUri" : "/api/pdf-storage/attachments/invoice-10003.pdf?hash=9e5e2631c6f5877d64cb3d40db46ec6eb48a3a92",
        "invoiceNumber" : "10001",
        "type" : "invoice-created"
      }
    }, {
      "triggeredBy" : "user",
      "comment" : "comment",
      "createdAt" : "2019-10-14T10:03:05.702",
      "details" : {
        "paymentProcessId" : "99b69bc3-5fb9-4cac-8d74-414bd6402774",
        "type" : "payment-voided"
      },
      "_links" : {
        "payment-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/114f787b-2d0a-4e4d-91a8-06e47a20a7b4/processes/payments/99b69bc3-5fb9-4cac-8d74-414bd6402774"
        }
      }
    }, {
      "triggeredBy" : null,
      "comment" : null,
      "createdAt" : "2019-10-14T10:03:05.613",
      "details" : {
        "amount" : {
          "currency" : "EUR",
          "amount" : 0
        },
        "paymentId" : null,
        "paymentProcessId" : "99b69bc3-5fb9-4cac-8d74-414bd6402774",
        "type" : "payment-created"
      },
      "_links" : {
        "payment-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/114f787b-2d0a-4e4d-91a8-06e47a20a7b4/processes/payments/99b69bc3-5fb9-4cac-8d74-414bd6402774"
        }
      }
    }, {
      "triggeredBy" : "user",
      "comment" : "customer transfer",
      "createdAt" : "2019-10-14T10:03:05.434",
      "details" : {
        "amount" : {
          "currency" : "EUR",
          "amount" : 77.44
        },
        "paymentProcessId" : "cc47e495-2e92-4446-af3f-d6c543177046",
        "type" : "payment-paid"
      },
      "_links" : {
        "payment-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/114f787b-2d0a-4e4d-91a8-06e47a20a7b4/processes/payments/cc47e495-2e92-4446-af3f-d6c543177046"
        }
      }
    }, {
      "triggeredBy" : null,
      "comment" : null,
      "createdAt" : "2019-10-14T10:03:05.026",
      "details" : {
        "amount" : {
          "currency" : "EUR",
          "amount" : 77.44
        },
        "paymentId" : null,
        "paymentProcessId" : "cc47e495-2e92-4446-af3f-d6c543177046",
        "type" : "payment-created"
      },
      "_links" : {
        "payment-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/114f787b-2d0a-4e4d-91a8-06e47a20a7b4/processes/payments/cc47e495-2e92-4446-af3f-d6c543177046"
        }
      }
    }, {
      "triggeredBy" : null,
      "comment" : null,
      "createdAt" : "2019-10-14T10:03:04.931",
      "details" : {
        "type" : "order-created"
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/114f787b-2d0a-4e4d-91a8-06e47a20a7b4/events"
    }
  },
  "page" : {
    "size" : 10,
    "totalElements" : 8,
    "totalPages" : 1,
    "number" : 0
  }
}

Order Settings

The order settings resource is used to deal with various order-related configurations. It comprises the option to customize several notes on order documents such as invoiceCancelationNote, defaultDeliveryDateNote, and defaultInvoiceNote.

The fields related to orderNumberConfiguration and invoiceNumberConfiguration allow to control the structure of order and invoice numbers. A prefix can be defined for the respective number as well as a numeric suffix to start counting from. The length of the numeric suffix can also be configured.

A configuration such as

  • string prefix = 2017-shop-

  • next numeric suffix = 1000

  • numeric suffix length = 5

results in 2017-shop-01000, where the numeric suffix is increased for every order/invoice.

List order settings

A GET request is used to retrieve the order settings.

Required scopes

oset:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/order-settings' -i -X GET \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

invoiceCancelationNote

String

The invoice cancelation note to be printed on invoice cancelation documents.

defaultDeliveryDateNote

String

The default delivery date note to be printed on the invoice.

defaultInvoiceNote

String

The default invoice note to be printed on the invoice.

orderNumberConfiguration.stringPrefix

String

A customizable prefix that can be attached to all order numbers. Not mandatory.

orderNumberConfiguration.nextNumericSuffix

Number

The next numeric suffix used for the upcoming order. This value is increased each time an order is created.

orderNumberConfiguration.numericSuffixLength

Number

The length of the numeric part of the order number. Has 5 digits by default. If the numeric value is shorter, the value is padded with zeros to the left, e.g. 01000. If the value is longer, the numericSuffixLength is extended, e.g. 100000.

invoiceNumberConfiguration.stringPrefix

String

A customizable prefix that can be attached to all invoice numbers. Not mandatory.

invoiceNumberConfiguration.nextNumericSuffix

Number

The next numeric suffix used for the upcoming invoice. This value is increased each time an invoice is created.

invoiceNumberConfiguration.numericSuffixLength

Number

The length of the numeric part of the invoice number. Has 5 digits by default. If the numeric value is shorter, the value is padded with zeros to the left, e.g. 01000. If the value is longer, the numericSuffixLength is extended, e.g. 100000.

customOrderOpenMailText

String

A customizable text body for the email that is sent to the customer when an order has been placed in a shop. Merchants can adapt the email body to their needs in case the default text does not meet their requirements.

customOrderCanceledMailText

String

A customizable text body for the email that is sent to the customer when an order has been canceled. Merchants can adapt the email body to their needs in case the default text does not meet their requirements.

customInvoiceCustomerMailText

String

A customizable text body for the email that is sent to the customer with the invoice pdf attached. Merchants can adapt the email body to their needs in case the default text does not meet their requirements.

customInvoiceCanceledMailText

String

A customizable text body for the email that is sent to the customer with the invoice cancellation pdf attached. Merchants can adapt the email body to their needs in case the default text does not meet their requirements.

customOrderShippedMailText

String

A customizable text body for the email that is sent to inform the customer that items have been shipped. Merchants can adapt the email body to their needs in case the default text does not meet their requirements.

customOrderPendingMailText

String

A customizable text body for the email that is sent to inform the customer that the shipping process has been started. Merchants can adapt the email body to their needs in case the default text does not meet their requirements.

customOrderReturnedMailText

String

A customizable text body for the email that is sent to inform the customer that the merchant has received the returned items for an order. Merchants can adapt the email body to their needs in case the default text does not meet their requirements.

_links

Object

See Hypermedia

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1138

{
  "invoiceCancelationNote" : "Default cancelation note of current shop",
  "defaultDeliveryDateNote" : "Default delivery date note of current shop",
  "defaultInvoiceNote" : "Default invoice note of current shop",
  "orderNumberConfiguration" : {
    "stringPrefix" : "",
    "nextNumericSuffix" : 10001,
    "numericSuffixLength" : 5
  },
  "invoiceNumberConfiguration" : {
    "stringPrefix" : "",
    "nextNumericSuffix" : 10001,
    "numericSuffixLength" : 5
  },
  "customOrderOpenMailText" : "Custom mail text.customOrderOpenMailText",
  "customOrderCanceledMailText" : "Custom mail text.customOrderCanceledMailText",
  "customInvoiceCustomerMailText" : "Custom mail text.customInvoiceCustomerMailText",
  "customInvoiceCanceledMailText" : "Custom mail text.customInvoiceCanceledMailText",
  "customOrderShippedMailText" : "Custom mail text.customOrderShippedMailText",
  "customOrderPendingMailText" : "Custom mail text.customOrderPendingMailText",
  "customOrderReturnedMailText" : "Custom mail text.customOrderReturnedMailText",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/order-settings"
    }
  }
}

Update order settings

A PUT request is used to update the order settings.

Required scopes

oset:u

Request body properties

Path Type Description Constraints

invoiceCancelationNote

String

The invoice cancelation note to be printed on invoice cancelation documents.

Length must be between 0 and 500 inclusive

defaultDeliveryDateNote

String

The default delivery date note to be printed on the invoice.

Length must be between 0 and 500 inclusive

defaultInvoiceNote

String

The default invoice note to be printed on the invoice.

Length must be between 0 and 500 inclusive

orderNumberConfiguration.stringPrefix

String

A customizable prefix that can be attached to all order numbers. Not mandatory.

Must not be null. Size must be between 0 and 20 inclusive

orderNumberConfiguration.nextNumericSuffix

Number

The next numeric suffix used for the upcoming order. This value is increased each time an order is created.

Numeric suffix can not have more than 20 digits

orderNumberConfiguration.numericSuffixLength

Number

The length of the numeric part of the order number. Has 5 digits by default. If the numeric value is shorter, the value is padded with zeros to the left, e.g. 01000. If the value is longer, the numericSuffixLength is extended, e.g. 100000.

Must be at least 1 and at most 20

invoiceNumberConfiguration.stringPrefix

String

A customizable prefix that can be attached to all invoice numbers. Not mandatory.

Must not be null. Size must be between 0 and 20 inclusive

invoiceNumberConfiguration.nextNumericSuffix

Number

The next numeric suffix used for the upcoming invoice. This value is increased each time an invoice is created.

Numeric suffix can not have more than 20 digits

invoiceNumberConfiguration.numericSuffixLength

Number

The length of the numeric part of the invoice number. Has 5 digits by default. If the numeric value is shorter, the value is padded with zeros to the left, e.g. 01000. If the value is longer, the numericSuffixLength is extended, e.g. 100000.

Must be at least 1 and at most 20

customOrderOpenMailText

String

A customizable text body for the email that is sent to the customer when an order has been placed in a shop. Merchants can adapt the email body to their needs in case the default text does not meet their requirements.

Length must be between 0 and 2047 inclusive. Must be safe HTML

customOrderCanceledMailText

String

A customizable text body for the email that is sent to the customer when an order has been canceled. Merchants can adapt the email body to their needs in case the default text does not meet their requirements.

Length must be between 0 and 2047 inclusive. Must be safe HTML

customInvoiceCustomerMailText

String

A customizable text body for the email that is sent to the customer with the invoice pdf attached. Merchants can adapt the email body to their needs in case the default text does not meet their requirements.

Length must be between 0 and 2047 inclusive. Must be safe HTML

customInvoiceCanceledMailText

String

A customizable text body for the email that is sent to the customer with the invoice cancellation pdf attached. Merchants can adapt the email body to their needs in case the default text does not meet their requirements.

Length must be between 0 and 2047 inclusive. Must be safe HTML

customOrderShippedMailText

String

A customizable text body for the email that is sent to inform the customer that items have been shipped. Merchants can adapt the email body to their needs in case the default text does not meet their requirements.

Length must be between 0 and 2047 inclusive. Must be safe HTML

customOrderPendingMailText

String

A customizable text body for the email that is sent to inform the customer that the shipping process has been started. Merchants can adapt the email body to their needs in case the default text does not meet their requirements.

Length must be between 0 and 2047 inclusive. Must be safe HTML

customOrderReturnedMailText

String

A customizable text body for the email that is sent to inform the customer that the merchant has received the returned items for an order. Merchants can adapt the email body to their needs in case the default text does not meet their requirements.

Length must be between 0 and 2047 inclusive. Must be safe HTML

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/order-settings' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{
  "invoiceCancelationNote" : "This is an invoice cancelation note",
  "defaultDeliveryDateNote" : "This is the default delivery date note",
  "defaultInvoiceNote" : "This is the default invoice note",
  "orderNumberConfiguration" : {
    "stringPrefix" : "2017-shop-",
    "nextNumericSuffix" : 1000,
    "numericSuffixLength" : 4
  },
  "invoiceNumberConfiguration" : {
    "stringPrefix" : "2017-invoice-",
    "nextNumericSuffix" : 1000,
    "numericSuffixLength" : 4
  },
  "customOrderOpenMailText" : " Your <br /> 1",
  "customOrderCanceledMailText" : " Your <br /> 2",
  "customInvoiceCustomerMailText" : " Your <br /> 3",
  "customInvoiceCanceledMailText" : " Your <br /> 4",
  "customOrderShippedMailText" : " Your <br /> 5",
  "customOrderPendingMailText" : " Your <br /> 6",
  "customOrderReturnedMailText" : " Your <br /> 7"
}'

Response body properties

Path Type Description

invoiceCancelationNote

String

The invoice cancelation note to be printed on invoice cancelation documents.

defaultDeliveryDateNote

String

The default delivery date note to be printed on the invoice.

defaultInvoiceNote

String

The default invoice note to be printed on the invoice.

orderNumberConfiguration.stringPrefix

String

A customizable prefix that can be attached to all order numbers. Not mandatory.

orderNumberConfiguration.nextNumericSuffix

Number

The next numeric suffix used for the upcoming order. This value is increased each time an order is created.

orderNumberConfiguration.numericSuffixLength

Number

The length of the numeric part of the order number. Has 5 digits by default. If the numeric value is shorter, the value is padded with zeros to the left, e.g. 01000. If the value is longer, the numericSuffixLength is extended, e.g. 100000.

invoiceNumberConfiguration.stringPrefix

String

A customizable prefix that can be attached to all invoice numbers. Not mandatory.

invoiceNumberConfiguration.nextNumericSuffix

Number

The next numeric suffix used for the upcoming invoice. This value is increased each time an invoice is created.

invoiceNumberConfiguration.numericSuffixLength

Number

The length of the numeric part of the invoice number. Has 5 digits by default. If the numeric value is shorter, the value is padded with zeros to the left, e.g. 01000. If the value is longer, the numericSuffixLength is extended, e.g. 100000.

customOrderOpenMailText

String

A customizable text body for the email that is sent to the customer when an order has been placed in a shop. Merchants can adapt the email body to their needs in case the default text does not meet their requirements.

customOrderCanceledMailText

String

A customizable text body for the email that is sent to the customer when an order has been canceled. Merchants can adapt the email body to their needs in case the default text does not meet their requirements.

customInvoiceCustomerMailText

String

A customizable text body for the email that is sent to the customer with the invoice pdf attached. Merchants can adapt the email body to their needs in case the default text does not meet their requirements.

customInvoiceCanceledMailText

String

A customizable text body for the email that is sent to the customer with the invoice cancellation pdf attached. Merchants can adapt the email body to their needs in case the default text does not meet their requirements.

customOrderShippedMailText

String

A customizable text body for the email that is sent to inform the customer that items have been shipped. Merchants can adapt the email body to their needs in case the default text does not meet their requirements.

customOrderPendingMailText

String

A customizable text body for the email that is sent to inform the customer that the shipping process has been started. Merchants can adapt the email body to their needs in case the default text does not meet their requirements.

customOrderReturnedMailText

String

A customizable text body for the email that is sent to inform the customer that the merchant has received the returned items for an order. Merchants can adapt the email body to their needs in case the default text does not meet their requirements.

_links

Object

See Hypermedia

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 938

{
  "invoiceCancelationNote" : "This is an invoice cancelation note",
  "defaultDeliveryDateNote" : "This is the default delivery date note",
  "defaultInvoiceNote" : "This is the default invoice note",
  "orderNumberConfiguration" : {
    "stringPrefix" : "2017-shop-",
    "nextNumericSuffix" : 1000,
    "numericSuffixLength" : 4
  },
  "invoiceNumberConfiguration" : {
    "stringPrefix" : "2017-invoice-",
    "nextNumericSuffix" : 1000,
    "numericSuffixLength" : 4
  },
  "customOrderOpenMailText" : " Your <br /> 1",
  "customOrderCanceledMailText" : " Your <br /> 2",
  "customInvoiceCustomerMailText" : " Your <br /> 3",
  "customInvoiceCanceledMailText" : " Your <br /> 4",
  "customOrderShippedMailText" : " Your <br /> 5",
  "customOrderPendingMailText" : " Your <br /> 6",
  "customOrderReturnedMailText" : " Your <br /> 7",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/order-settings"
    }
  }
}

Payment Methods

The payment method resources are used to get information about the payment methods of a shop. Payment methods refer to the options provided to a merchant’s customer at checkout, e.g. the option to pay with a credit card or via PayPal.

Show payment method details

A GET request is used to retrieve the details of a payment method.

Required scopes

pymt:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/payment-methods/02a77038-d4ca-42b1-9365-f96b14deb5c4' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_id

String

The immutable, unique identifier of the requested resource.

position

Number

The sorting position of the payment method in the merchant’s cockpit in relation to other payment methods.

officialName

String

The official name of the payment method chosen by the merchant during setup.

officialDescription

String

The official description of the payment method chosen by the merchant during setup.

name

String

The name of the payment method that is used during checkout.

description

String

Description of the payment method that is used during checkout.

activated

Boolean

Indicates if a payment method is active. Can be true or false.

taxClass

String

The tax class. Can be REGULAR, REDUCED, or EXEMPT.

discountOrFee

Object

The details about the fee to be payed or discount to be granted for this payment method.

discountOrFee.type

String

The discount or fee can be an absolute or a percentage based value. Can be one of PERCENTAGE or ABSOLUTE. ABSOLUTE contains another attribute absoluteValue with a positive or negative price. PERCENTAGE contains another attribute percentageValue with a negative or positive percentage value.

serviceableCountries

Array

The list of target countries this payment method can be used in.

minimumOrderValue

Object

The minimum value of the cart so that this payment method can be used.

onlinePayment

Boolean

Indicates if the payment method is an online payment. Can be true or false.

activeLogoSet

Null

The name of the currently selected logo set. Can be TILE, DETAILS, LIST, or STOREFRONT. (official is always the fallback).

workflow

String

The payment workflow for the current payment. Can be one of PAYMENT_ON_SELECTION, EMBEDDED_ON_SELECTION, PAYMENT_ON_BUY, or EMBEDDED_ON_BUY.

_links

Object

See Hypermedia

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1638

{
  "_id" : "02a77038-d4ca-42b1-9365-f96b14deb5c4",
  "name" : "Converge",
  "description" : "Pay by Converge.",
  "officialName" : "Converge",
  "officialDescription" : "Pay by Converge.",
  "taxClass" : "REGULAR",
  "discountOrFee" : {
    "type" : "ABSOLUTE",
    "absoluteValue" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2
    },
    "percentageValue" : null
  },
  "position" : 1,
  "serviceableCountries" : [ "DE" ],
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 10
  },
  "activated" : true,
  "activeLogoSet" : null,
  "onlinePayment" : true,
  "workflow" : "PAYMENT_ON_SELECTION",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/02a77038-d4ca-42b1-9365-f96b14deb5c4"
    },
    "payment-method" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/02a77038-d4ca-42b1-9365-f96b14deb5c4"
    },
    "payment-method-definition-status" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-signup/merchant-accounts/converge-sandbox"
    },
    "deactivate-payment-method" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/02a77038-d4ca-42b1-9365-f96b14deb5c4/deactivate"
    },
    "logo-storefront" : {
      "href" : "http://storefront-logo.com"
    },
    "logo-details" : {
      "href" : "http://details-logo.com"
    },
    "logo-list" : {
      "href" : "http://list-logo.com"
    },
    "logo-tile" : {
      "href" : "http://tile-logo.com"
    },
    "payment-method-definition" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/02a77038-d4ca-42b1-9365-f96b14deb5c4/payment-method-definition"
    }
  }
}

List payment methods

A GET request is used to list all payment methods in a paged way.

Required scopes

pymt:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/payment-methods' -i -X GET \
    -H 'Content-Type: application/hal+json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2861

{
  "_embedded" : {
    "payment-methods" : [ {
      "_id" : "6585e255-a958-4879-9e87-4eba3de5c8a3",
      "name" : "Converge",
      "description" : "Pay by Converge.",
      "officialName" : "Converge",
      "officialDescription" : "Pay by Converge.",
      "taxClass" : "REGULAR",
      "discountOrFee" : {
        "type" : "ABSOLUTE",
        "absoluteValue" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 2
        },
        "percentageValue" : null
      },
      "position" : 1,
      "serviceableCountries" : [ "DE" ],
      "minimumOrderValue" : null,
      "activated" : true,
      "activeLogoSet" : null,
      "onlinePayment" : false,
      "workflow" : null,
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/6585e255-a958-4879-9e87-4eba3de5c8a3"
        },
        "payment-method" : {
          "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/6585e255-a958-4879-9e87-4eba3de5c8a3"
        },
        "deactivate-payment-method" : {
          "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/6585e255-a958-4879-9e87-4eba3de5c8a3/deactivate"
        },
        "payment-method-definition" : {
          "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/6585e255-a958-4879-9e87-4eba3de5c8a3/payment-method-definition"
        }
      }
    }, {
      "_id" : "57b0c8ae-eae0-4894-aaf3-8e4768fd5ed0",
      "name" : "Credit card",
      "description" : "Pay by credit card.",
      "officialName" : "Credit card",
      "officialDescription" : "Pay by credit card.",
      "taxClass" : "REGULAR",
      "discountOrFee" : {
        "type" : "PERCENTAGE",
        "absoluteValue" : null,
        "percentageValue" : 0.02
      },
      "position" : 2,
      "serviceableCountries" : [ "DE", "GB" ],
      "minimumOrderValue" : {
        "currency" : "EUR",
        "amount" : 20
      },
      "activated" : false,
      "activeLogoSet" : null,
      "onlinePayment" : false,
      "workflow" : null,
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/57b0c8ae-eae0-4894-aaf3-8e4768fd5ed0"
        },
        "payment-method" : {
          "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/57b0c8ae-eae0-4894-aaf3-8e4768fd5ed0"
        },
        "activate-payment-method" : {
          "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/57b0c8ae-eae0-4894-aaf3-8e4768fd5ed0/activate"
        },
        "payment-method-definition" : {
          "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/57b0c8ae-eae0-4894-aaf3-8e4768fd5ed0/payment-method-definition"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods?page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

Update payment method

A PUT request is used to update a payment method.

Required scopes

pymt:u

Request body properties

Path Type Description Constraints

name

String

The name of the payment method that is used during checkout.

Length must be between 0 and 255 inclusive. Must not be empty

description

String

Description of the payment method that is used during checkout.

Length must be between 0 and 4095 inclusive

discountOrFee

Object

The details about the fee to be payed or discount to be granted for this payment method.

discountOrFee.type

String

The discount or fee can be an absolute or a percentage based value. Can be one of PERCENTAGE or ABSOLUTE. ABSOLUTE contains another attribute absoluteValue with a positive or negative price. PERCENTAGE contains another attribute percentageValue with a negative or positive percentage value.

serviceableCountries

Array

The list of target countries this payment method can be used in.

Each country code must be officially assigned (see ISO 3166-1 Alpha-2)

minimumOrderValue

Object

The minimum value of the cart so that this payment method can be used.

taxClass

String

The tax class. Can be REGULAR, REDUCED, or EXEMPT.

Length must be between 0 and 15 inclusive. Must not be null

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/payment-methods/d10d0b02-ac48-414d-b787-82a16e6cb0ff' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{
  "name" : "Another name",
  "description" : "Pay by Converge.",
  "taxClass" : "REGULAR",
  "discountOrFee" : {
    "type" : "ABSOLUTE",
    "absoluteValue" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2.0
    }
  },
  "serviceableCountries" : [ "DE" ],
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 10.0
  }
}'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1205

{
  "_id" : "d10d0b02-ac48-414d-b787-82a16e6cb0ff",
  "name" : "Another name",
  "description" : "Pay by Converge.",
  "officialName" : "Converge",
  "officialDescription" : "Pay by Converge.",
  "taxClass" : "REGULAR",
  "discountOrFee" : {
    "type" : "ABSOLUTE",
    "absoluteValue" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2
    },
    "percentageValue" : null
  },
  "position" : 1,
  "serviceableCountries" : [ "DE" ],
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 10
  },
  "activated" : true,
  "activeLogoSet" : null,
  "onlinePayment" : false,
  "workflow" : null,
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/d10d0b02-ac48-414d-b787-82a16e6cb0ff"
    },
    "payment-method" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/d10d0b02-ac48-414d-b787-82a16e6cb0ff"
    },
    "deactivate-payment-method" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/d10d0b02-ac48-414d-b787-82a16e6cb0ff/deactivate"
    },
    "payment-method-definition" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/d10d0b02-ac48-414d-b787-82a16e6cb0ff/payment-method-definition"
    }
  }
}

Sort payment methods

A PUT request is used to sort payment methods.

Required scopes

pymt:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/payment-methods' -i -X PUT \
    -H 'Content-Type: text/uri-list' \
    -H 'Authorization: Bearer <Access token>' \
    -d 'https://api-shop.beyondshop.cloud/api/payment-methods/4282ce29-a211-4160-9a9d-3a5541deb3e2
https://api-shop.beyondshop.cloud/api/payment-methods/75090d19-3507-46dc-a6b7-70740419ea15
https://api-shop.beyondshop.cloud/api/payment-methods/f30896da-7dbf-4769-a1d8-1b9cb08adad3
https://api-shop.beyondshop.cloud/api/payment-methods/38b51383-82ef-45f6-b810-94774b40f940'

Example response

HTTP/1.1 204 No Content
Location: https://api-shop.beyondshop.cloud/api/payment-methods

Activate a payment method

A POST request is used to activate a payment method.

Required scopes

pymt:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/payment-methods/edf2423b-7901-4661-a870-cb5280114b5b/activate' -i -X POST \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1145

{
  "_id" : "edf2423b-7901-4661-a870-cb5280114b5b",
  "name" : "Credit card",
  "description" : "Pay by credit card.",
  "officialName" : "Credit card",
  "officialDescription" : "Pay by credit card.",
  "taxClass" : "REGULAR",
  "discountOrFee" : {
    "type" : "PERCENTAGE",
    "absoluteValue" : null,
    "percentageValue" : 0.02
  },
  "position" : 1,
  "serviceableCountries" : [ "DE", "GB" ],
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 20
  },
  "activated" : true,
  "activeLogoSet" : null,
  "onlinePayment" : false,
  "workflow" : null,
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/edf2423b-7901-4661-a870-cb5280114b5b"
    },
    "payment-method" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/edf2423b-7901-4661-a870-cb5280114b5b"
    },
    "deactivate-payment-method" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/edf2423b-7901-4661-a870-cb5280114b5b/deactivate"
    },
    "payment-method-definition" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/edf2423b-7901-4661-a870-cb5280114b5b/payment-method-definition"
    }
  }
}

Deactivate a payment method

A POST request is used to deactivate a payment method.

Required scopes

pymt:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/payment-methods/5bfe70ea-782a-409e-b3a1-04d7f0bee27d/deactivate' -i -X POST \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1142

{
  "_id" : "5bfe70ea-782a-409e-b3a1-04d7f0bee27d",
  "name" : "Credit card",
  "description" : "Pay by credit card.",
  "officialName" : "Credit card",
  "officialDescription" : "Pay by credit card.",
  "taxClass" : "REGULAR",
  "discountOrFee" : {
    "type" : "PERCENTAGE",
    "absoluteValue" : null,
    "percentageValue" : 0.02
  },
  "position" : 2,
  "serviceableCountries" : [ "DE", "GB" ],
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 20
  },
  "activated" : false,
  "activeLogoSet" : null,
  "onlinePayment" : false,
  "workflow" : null,
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/5bfe70ea-782a-409e-b3a1-04d7f0bee27d"
    },
    "payment-method" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/5bfe70ea-782a-409e-b3a1-04d7f0bee27d"
    },
    "activate-payment-method" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/5bfe70ea-782a-409e-b3a1-04d7f0bee27d/activate"
    },
    "payment-method-definition" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/5bfe70ea-782a-409e-b3a1-04d7f0bee27d/payment-method-definition"
    }
  }
}

Products

The products resource is used to manage products of a shop.

List products including variation products

A GET request will list all of the products in a paged manner. The returned data is an excerpt projection, which includes a small subset of product properties.

Required scopes

prod:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products' -i -X GET \
    -H 'Content-Type: application/hal+json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_links

Object

See Hypermedia

page

Object

See Pagination

_embedded.products[].sku

String

The stock keeping unit (SKU) corresponding to the product.

_embedded.products[].name

String

The name of the product.

_embedded.products[].visible

Boolean

Indicates if the product is visible in the online shop. Can be true or false.

_embedded.products[].tags

Array

The tags assigned to a product.

_embedded.products[].salesPrice

Object

The price of the product.

_embedded.products[].salesPrice.amount

Number

The amount of the sales price.

_embedded.products[].salesPrice.currency

String

The currency of the sales price.

_embedded.products[].salesPrice.taxModel

String

The tax model of the sales price. Can be GROSS or NET.

_embedded.products[].listPrice

Object

The previous price of a product that is currently on offer.

_embedded.products[].listPrice.amount

Number

The amount of the list price.

_embedded.products[].listPrice.currency

String

The currency of the list price.

_embedded.products[].listPrice.taxModel

String

The tax model of the list price. Can be GROSS or NET.

_embedded.products[].manufacturerPrice

Object

The manufacturer’s suggested retail price of the product.

_embedded.products[].manufacturerPrice.amount

Number

The amount of the manufacturer’s suggested retail price.

_embedded.products[].manufacturerPrice.currency

String

The currency of the manufacturer’s suggested retail price.

_embedded.products[].manufacturerPrice.taxModel

String

The tax model of the manufacturer’s suggested retail price. Can be GROSS or NET.

_embedded.products[]._id

String

The immutable, unique identifier of the requested resource.

_embedded.products[].salesPrice.derivedPrice

Object

The calculated price with taxes applied (read-only).

_embedded.products[].listPrice.derivedPrice

Object

The calculated price with taxes applied (read-only).

_embedded.products[].manufacturerPrice.derivedPrice

Object

The calculated manufacturer’s suggested retail price with taxes applied (read-only).

_embedded.products[].description

String

The description of the product.

_embedded.products[].manufacturer

String

The manufacturer of the product.

_embedded.products[].visible

Boolean

Indicates if the product is visible in the online shop. Can be true or false.

_embedded.products[].onSale

Boolean

Indicates if the product is on offer. Can be true or false.

_embedded.products[].productIdentifiers

Array

The list of product identifiers.

_embedded.products[].productIdentifiers[].type

String

The product code to identify and classify the product. Can be EAN, UPC, ISBN, or MPN.

_embedded.products[].productIdentifiers[].value

String

The actual value of the product identifier.

_embedded.products[].essentialFeatures

String

The essential product properties of the product. Shown in the cart and checkout. In Germany mandatory field in online shops according to §312j Abs. 2 BGB (German Civil Code).

_embedded.products[].tags

Array

The tags assigned to a product.

_embedded.products[].taxClass

String

The tax class. Can be REGULAR, REDUCED, or EXEMPT.

_embedded.products[].shippingWeight

Number

The weight of the product including packaging in g.

_embedded.products[].maxOrderQuantity

Number

Displays how often this product can be ordered at maximum in one order.

_embedded.products[].shippingPeriod.minDays

Number

The minimum required days for shipping.

_embedded.products[].shippingPeriod.maxDays

Number

The maximum required days for shipping.

_embedded.products[].shippingPeriod.displayUnit

String

The unit to show the shipping period. Use DAYS or WEEKS.

_embedded.products[].shippingDimension.length

Number

The length of the product including packaging in mm.

_embedded.products[].shippingDimension.width

Number

The width of the product including packaging in mm.

_embedded.products[].shippingDimension.height

Number

The height of the product including packaging in mm.

_embedded.products[].refPrice

Object

The reference price of a product.

_embedded.products[].refPrice.refQuantity

Number

The reference quantity of the product.

_embedded.products[].refPrice.quantity

Number

The quantity in the product.

_embedded.products[].refPrice.unit

String

The unit of the quantity.

_embedded.products[].refPrice.price

Object

The price information scaled to a standardised base unit, according to the German base price regulation “Preisangabenverordnung” (PAngV), e.g. 1 l = 1.20 EUR. Is null if no reference amount is specified for the product.

_embedded.products[].variationAttributes

Array

The variation attributes with its values.

_embedded.products[].lastModifiedAt

String

The date and time the product was modified.

_embedded.products[]._embedded.availability

Object

The information about the availability of the product.

Links

Relation Description

search

The link to product search endpoints.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 4475

{
  "_embedded" : {
    "products" : [ {
      "_embedded" : {
        "availability" : {
          "availabilityState" : "IN_STOCK",
          "availableStock" : 20,
          "stockThreshold" : 2,
          "purchasable" : true,
          "_links" : {
            "self" : {
              "href" : "https://api-shop.beyondshop.cloud/api/products/1ccd74e4-7e09-4db2-9eff-19c951ccb1d5/availability"
            }
          }
        }
      },
      "lastModifiedAt" : "2019-10-11T08:08:02.046",
      "sku" : "vino020",
      "salesPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 8.7,
        "derivedPrice" : {
          "taxModel" : "NET",
          "currency" : "EUR",
          "amount" : 7.05,
          "taxRate" : 0.19
        }
      },
      "listPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 10.95,
        "derivedPrice" : {
          "taxModel" : "NET",
          "currency" : "EUR",
          "amount" : 8.87,
          "taxRate" : 0.19
        }
      },
      "manufacturerPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 99.95,
        "derivedPrice" : {
          "taxModel" : "NET",
          "currency" : "EUR",
          "amount" : 80.96,
          "taxRate" : 0.19
        }
      },
      "onSale" : true,
      "tags" : [ "Bestseller", "Red Wine", "Sale" ],
      "productIdentifiers" : [ {
        "type" : "EAN",
        "value" : "9780134308135"
      } ],
      "visible" : true,
      "taxClass" : "REGULAR",
      "shippingWeight" : 100,
      "maxOrderQuantity" : 6,
      "shippingDimension" : {
        "length" : 1500,
        "width" : 1000,
        "height" : 2000
      },
      "refPrice" : {
        "refQuantity" : 1,
        "unit" : "LITER",
        "quantity" : 0.75,
        "price" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 11.6,
          "derivedPrice" : {
            "taxModel" : "NET",
            "currency" : "EUR",
            "amount" : 9.4,
            "taxRate" : 0.19
          }
        }
      },
      "shippingPeriod" : {
        "minDays" : 2,
        "maxDays" : 4,
        "displayUnit" : "WEEKS"
      },
      "name" : "Rioja Castillo de Puerto (2013)",
      "description" : "Spain\nRioja Tempranillo",
      "manufacturer" : "Grape Vineyard",
      "essentialFeatures" : "Dry. 12% alcohol. Best vine variety.",
      "variationAttributes" : [ ],
      "_id" : "1ccd74e4-7e09-4db2-9eff-19c951ccb1d5",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/1ccd74e4-7e09-4db2-9eff-19c951ccb1d5"
        },
        "product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/1ccd74e4-7e09-4db2-9eff-19c951ccb1d5"
        },
        "availability" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/1ccd74e4-7e09-4db2-9eff-19c951ccb1d5/availability"
        },
        "attributes" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/1ccd74e4-7e09-4db2-9eff-19c951ccb1d5/attributes"
        },
        "attachments" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/1ccd74e4-7e09-4db2-9eff-19c951ccb1d5/attachments"
        },
        "images" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/1ccd74e4-7e09-4db2-9eff-19c951ccb1d5/images"
        },
        "amazon" : {
          "href" : "http://amazon/amazon-products/1ccd74e4-7e09-4db2-9eff-19c951ccb1d5"
        },
        "google-shopping" : {
          "href" : "http://google-shopping/google-products/1ccd74e4-7e09-4db2-9eff-19c951ccb1d5"
        },
        "default-image" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/1ccd74e4-7e09-4db2-9eff-19c951ccb1d5/default-image"
        },
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/photostore-2.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
          "templated" : true
        },
        "default-image-metadata" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/photostore-2.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998&download=no"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products?page=0&size=20"
    },
    "search" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/search"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

Create product

A POST request is used to create a product.

Required scopes

prod:c

Request body properties

Path Type Description Constraints

sku

String

The stock keeping unit (SKU) corresponding to the product.

Must match the regular expression ^(?!\s*$).+. Size must be between 1 and 255 inclusive

name

String

The name of the product.

Length must be between 0 and 255 inclusive

visible

Boolean

Indicates if the product is visible in the online shop. Can be true or false.

tags

Array

The tags assigned to a product.

salesPrice

Object

The price of the product.

Must match the shop’s tax model

salesPrice.amount

Number

The amount of the sales price.

salesPrice.currency

String

The currency of the sales price.

salesPrice.taxModel

String

The tax model of the sales price. Can be GROSS or NET.

listPrice

Object

The previous price of a product that is currently on offer.

listPrice.amount

Number

The amount of the list price.

listPrice.currency

String

The currency of the list price.

listPrice.taxModel

String

The tax model of the list price. Can be GROSS or NET.

manufacturerPrice

Object

The manufacturer’s suggested retail price of the product.

manufacturerPrice.amount

Number

The amount of the manufacturer’s suggested retail price.

manufacturerPrice.currency

String

The currency of the manufacturer’s suggested retail price.

manufacturerPrice.taxModel

String

The tax model of the manufacturer’s suggested retail price. Can be GROSS or NET.

description

String

The description of the product.

Length must be between 0 and 4095 inclusive

manufacturer

String

The manufacturer of the product.

Length must be between 0 and 255 inclusive

visible

Boolean

Indicates if the product is visible in the online shop. Can be true or false.

onSale

Boolean

Indicates if the product is on offer. Can be true or false.

productIdentifiers

Array

The list of product identifiers.

productIdentifiers[].type

String

The product code to identify and classify the product. Can be EAN, UPC, ISBN, or MPN.

productIdentifiers[].value

String

The actual value of the product identifier.

essentialFeatures

String

The essential product properties of the product. Shown in the cart and checkout. In Germany mandatory field in online shops according to §312j Abs. 2 BGB (German Civil Code).

Length must be between 0 and 4095 inclusive

tags

Array

The tags assigned to a product.

taxClass

String

The tax class. Can be REGULAR, REDUCED, or EXEMPT.

Must not be null

shippingWeight

Number

The weight of the product including packaging in g.

maxOrderQuantity

Number

Displays how often this product can be ordered at maximum in one order.

shippingPeriod.minDays

Number

The minimum required days for shipping.

shippingPeriod.maxDays

Number

The maximum required days for shipping.

shippingPeriod.displayUnit

String

The unit to show the shipping period. Use DAYS or WEEKS.

shippingDimension.length

Number

The length of the product including packaging in mm.

shippingDimension.width

Number

The width of the product including packaging in mm.

shippingDimension.height

Number

The height of the product including packaging in mm.

refPrice

Object

The reference price of a product.

refPrice.refQuantity

Number

The reference quantity of the product.

refPrice.quantity

Number

The quantity in the product.

refPrice.unit

String

The unit of the quantity.

refPrice.price

Object

The price information scaled to a standardised base unit, according to the German base price regulation “Preisangabenverordnung” (PAngV), e.g. 1 l = 1.20 EUR. Is null if no reference amount is specified for the product.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{
  "sku" : "123456789-001",
  "name" : "Rioja Castillo de Puerto (2013)",
  "description" : "Spain\nRioja Tempranillo",
  "manufacturer" : "Grape Vineyard",
  "essentialFeatures" : "Dry. 12% alcohol. Best vine variety.",
  "tags" : [ "Bestseller", "Red Wine", "Sale" ],
  "productIdentifiers" : [ {
    "type" : "EAN",
    "value" : "9780134308135"
  } ],
  "salesPrice" : {
    "taxModel" : "GROSS",
    "amount" : 8.7,
    "currency" : "EUR"
  },
  "listPrice" : {
    "taxModel" : "GROSS",
    "amount" : 10.95,
    "currency" : "EUR"
  },
  "manufacturerPrice" : {
    "taxModel" : "GROSS",
    "amount" : 99.95,
    "currency" : "EUR"
  },
  "onSale" : true,
  "visible" : true,
  "taxClass" : "REGULAR",
  "shippingWeight" : 100,
  "maxOrderQuantity" : 6,
  "shippingDimension" : {
    "length" : 1500,
    "width" : 1000,
    "height" : 2000
  },
  "refPrice" : {
    "refQuantity" : 1,
    "unit" : "LITER",
    "quantity" : 0.75,
    "price" : {
      "taxModel" : "GROSS",
      "amount" : 11.6,
      "currency" : "EUR"
    }
  },
  "shippingPeriod" : {
    "minDays" : 2,
    "maxDays" : 4,
    "displayUnit" : "WEEKS"
  }
}'

Example response

HTTP/1.1 201 Created
Location: https://api-shop.beyondshop.cloud/api/products/6a98a58c-7586-4255-a0df-89c41d62932f
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 3018

{
  "_embedded" : {
    "availability" : {
      "availabilityState" : "IN_STOCK",
      "availableStock" : null,
      "stockThreshold" : null,
      "purchasable" : true,
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/6a98a58c-7586-4255-a0df-89c41d62932f/availability"
        }
      }
    }
  },
  "lastModifiedAt" : "2019-10-11T08:08:03.777",
  "sku" : "123456789-001",
  "salesPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 8.7,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 7.9091,
      "taxRate" : 0.1
    }
  },
  "listPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 10.95,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 9.9545,
      "taxRate" : 0.1
    }
  },
  "manufacturerPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 99.95,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 90.864,
      "taxRate" : 0.1
    }
  },
  "onSale" : true,
  "tags" : [ "Bestseller", "Red Wine", "Sale" ],
  "productIdentifiers" : [ {
    "type" : "EAN",
    "value" : "9780134308135"
  } ],
  "visible" : true,
  "taxClass" : "REGULAR",
  "shippingWeight" : 100,
  "maxOrderQuantity" : 6,
  "shippingDimension" : {
    "length" : 1500,
    "width" : 1000,
    "height" : 2000
  },
  "refPrice" : {
    "refQuantity" : 1,
    "unit" : "LITER",
    "quantity" : 0.75,
    "price" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 11.6,
      "derivedPrice" : {
        "taxModel" : "NET",
        "currency" : "EUR",
        "amount" : 10.545,
        "taxRate" : 0.1
      }
    }
  },
  "shippingPeriod" : {
    "minDays" : 2,
    "maxDays" : 4,
    "displayUnit" : "WEEKS"
  },
  "name" : "Rioja Castillo de Puerto (2013)",
  "description" : "Spain\nRioja Tempranillo",
  "manufacturer" : "Grape Vineyard",
  "essentialFeatures" : "Dry. 12% alcohol. Best vine variety.",
  "variationAttributes" : [ ],
  "_id" : "6a98a58c-7586-4255-a0df-89c41d62932f",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/6a98a58c-7586-4255-a0df-89c41d62932f"
    },
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/6a98a58c-7586-4255-a0df-89c41d62932f"
    },
    "availability" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/6a98a58c-7586-4255-a0df-89c41d62932f/availability"
    },
    "attributes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/6a98a58c-7586-4255-a0df-89c41d62932f/attributes"
    },
    "attachments" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/6a98a58c-7586-4255-a0df-89c41d62932f/attachments"
    },
    "images" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/6a98a58c-7586-4255-a0df-89c41d62932f/images"
    },
    "default-image" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/6a98a58c-7586-4255-a0df-89c41d62932f/default-image"
    }
  }
}

Create variation product

A POST request is used to create a variation product and all its variations.

Required scopes

prod:c

Request body properties

Path Type Description Constraints

name

String

The name of the product.

Length must be between 0 and 255 inclusive

visible

Boolean

Indicates if the product is visible in the online shop. Can be true or false.

tags

Array

The tags assigned to a product.

salesPrice

Object

The price of the product.

Must match the shop’s tax model

salesPrice.amount

Number

The amount of the sales price.

salesPrice.currency

String

The currency of the sales price.

salesPrice.taxModel

String

The tax model of the sales price. Can be GROSS or NET.

listPrice

Object

The previous price of a product that is currently on offer.

listPrice.amount

Number

The amount of the list price.

listPrice.currency

String

The currency of the list price.

listPrice.taxModel

String

The tax model of the list price. Can be GROSS or NET.

manufacturerPrice

Object

The manufacturer’s suggested retail price of the product.

manufacturerPrice.amount

Number

The amount of the manufacturer’s suggested retail price.

manufacturerPrice.currency

String

The currency of the manufacturer’s suggested retail price.

manufacturerPrice.taxModel

String

The tax model of the manufacturer’s suggested retail price. Can be GROSS or NET.

description

String

The description of the product.

Length must be between 0 and 4095 inclusive

manufacturer

String

The manufacturer of the product.

Length must be between 0 and 255 inclusive

visible

Boolean

Indicates if the product is visible in the online shop. Can be true or false.

onSale

Boolean

Indicates if the product is on offer. Can be true or false.

productIdentifiers

Array

The list of product identifiers.

productIdentifiers[].type

String

The product code to identify and classify the product. Can be EAN, UPC, ISBN, or MPN.

productIdentifiers[].value

String

The actual value of the product identifier.

essentialFeatures

Null

The essential product properties of the product. Shown in the cart and checkout. In Germany mandatory field in online shops according to §312j Abs. 2 BGB (German Civil Code).

Length must be between 0 and 4095 inclusive

tags

Array

The tags assigned to a product.

taxClass

String

The tax class. Can be REGULAR, REDUCED, or EXEMPT.

Must not be null

shippingWeight

Null

The weight of the product including packaging in g.

maxOrderQuantity

Null

Displays how often this product can be ordered at maximum in one order.

shippingPeriod.minDays

Number

The minimum required days for shipping.

shippingPeriod.maxDays

Number

The maximum required days for shipping.

shippingPeriod.displayUnit

String

The unit to show the shipping period. Use DAYS or WEEKS.

shippingDimension.length

Number

The length of the product including packaging in mm.

shippingDimension.width

Number

The width of the product including packaging in mm.

shippingDimension.height

Number

The height of the product including packaging in mm.

refPrice

Null

The reference price of a product.

refPrice.refQuantity

Number

The reference quantity of the product.

refPrice.quantity

Number

The quantity in the product.

refPrice.unit

String

The unit of the quantity.

refPrice.price

Object

The price information scaled to a standardised base unit, according to the German base price regulation “Preisangabenverordnung” (PAngV), e.g. 1 l = 1.20 EUR. Is null if no reference amount is specified for the product.

variationAttributes

Array

The variation attributes with its values.

Variation attributes must be less or equal to {MAX_VARIATION_ATTRIBUTES} and combine to less or equal than {MAX_VARIATIONS} variations. Variation attributes requires the following features: {VARIATION_ATTRIBUTE_FEATURE_NAME} and {VARIATION_FEATURE_NAME}. Variation attributes requires unique display name

variationAttributes[].values

Array

The values for a variation attribute defined by the merchant, e.g. the detailed sizes such as S, M, L, XL.

variationAttributes[].displayName

String

The name of the variation attribute defined by the merchant, e.g. name, size, or color.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{
  "salesPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 29.99
  },
  "listPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 39.99
  },
  "manufacturerPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 40.99
  },
  "onSale" : true,
  "tags" : [ "Shirt", "Summer", "Sale" ],
  "productIdentifiers" : [ ],
  "visible" : true,
  "taxClass" : "REGULAR",
  "shippingWeight" : null,
  "maxOrderQuantity" : null,
  "shippingDimension" : {
    "length" : 2000,
    "width" : 750,
    "height" : 500
  },
  "refPrice" : null,
  "shippingPeriod" : {
    "minDays" : 3,
    "maxDays" : 5,
    "displayUnit" : "DAYS"
  },
  "name" : "Tony Highfinger, Poloshirt, Men",
  "description" : "100% cotton, regular fit, needs cold washing (max. 30°C), Fair Trade certified.",
  "manufacturer" : "Tony Highfinger",
  "essentialFeatures" : null,
  "variationAttributes" : [ {
    "displayName" : "size",
    "values" : [ "S", "M", "L", "XL" ]
  }, {
    "displayName" : "color",
    "values" : [ "Black", "White", "Grey" ]
  } ]
}'

Example response

HTTP/1.1 201 Created
Location: https://api-shop.beyondshop.cloud/api/products/8c43ac41-83c4-4789-a975-0c69fcdc2840
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2948

{
  "_embedded" : {
    "availability" : {
      "availabilityState" : "NOT_AVAILABLE",
      "availableStock" : null,
      "stockThreshold" : null,
      "purchasable" : false,
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/8c43ac41-83c4-4789-a975-0c69fcdc2840/availability"
        }
      }
    }
  },
  "lastModifiedAt" : "2019-10-11T08:09:19.768",
  "sku" : null,
  "salesPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 29.99,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 27.264,
      "taxRate" : 0.1
    }
  },
  "listPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 39.99,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 36.355,
      "taxRate" : 0.1
    }
  },
  "manufacturerPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 40.99,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 37.264,
      "taxRate" : 0.1
    }
  },
  "onSale" : true,
  "tags" : [ "Shirt", "Summer", "Sale" ],
  "productIdentifiers" : [ ],
  "visible" : true,
  "taxClass" : "REGULAR",
  "shippingWeight" : null,
  "maxOrderQuantity" : null,
  "shippingDimension" : {
    "length" : 2000,
    "width" : 750,
    "height" : 500
  },
  "refPrice" : null,
  "shippingPeriod" : {
    "minDays" : 3,
    "maxDays" : 5,
    "displayUnit" : "DAYS"
  },
  "name" : "Tony Highfinger, Poloshirt, Men",
  "description" : "100% cotton, regular fit, needs cold washing (max. 30°C), Fair Trade certified.",
  "manufacturer" : "Tony Highfinger",
  "essentialFeatures" : null,
  "variationAttributes" : [ {
    "displayName" : "size",
    "values" : [ "S", "M", "L", "XL" ]
  }, {
    "displayName" : "color",
    "values" : [ "Black", "White", "Grey" ]
  } ],
  "_id" : "8c43ac41-83c4-4789-a975-0c69fcdc2840",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/8c43ac41-83c4-4789-a975-0c69fcdc2840"
    },
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/8c43ac41-83c4-4789-a975-0c69fcdc2840"
    },
    "availability" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/8c43ac41-83c4-4789-a975-0c69fcdc2840/availability"
    },
    "attributes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/8c43ac41-83c4-4789-a975-0c69fcdc2840/attributes"
    },
    "attachments" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/8c43ac41-83c4-4789-a975-0c69fcdc2840/attachments"
    },
    "images" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/8c43ac41-83c4-4789-a975-0c69fcdc2840/images"
    },
    "default-image" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/8c43ac41-83c4-4789-a975-0c69fcdc2840/default-image"
    },
    "variations" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/8c43ac41-83c4-4789-a975-0c69fcdc2840/variations"
    }
  }
}

Show product details

A GET request is used to retrieve the details of a product.

Required scopes

prod:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/801e9349-a1d7-4dc7-926b-073cb1e478b3' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

sku

String

The stock keeping unit (SKU) corresponding to the product.

name

String

The name of the product.

visible

Boolean

Indicates if the product is visible in the online shop. Can be true or false.

tags

Array

The tags assigned to a product.

salesPrice

Object

The price of the product.

salesPrice.amount

Number

The amount of the sales price.

salesPrice.currency

String

The currency of the sales price.

salesPrice.taxModel

String

The tax model of the sales price. Can be GROSS or NET.

listPrice

Object

The previous price of a product that is currently on offer.

listPrice.amount

Number

The amount of the list price.

listPrice.currency

String

The currency of the list price.

listPrice.taxModel

String

The tax model of the list price. Can be GROSS or NET.

manufacturerPrice

Object

The manufacturer’s suggested retail price of the product.

manufacturerPrice.amount

Number

The amount of the manufacturer’s suggested retail price.

manufacturerPrice.currency

String

The currency of the manufacturer’s suggested retail price.

manufacturerPrice.taxModel

String

The tax model of the manufacturer’s suggested retail price. Can be GROSS or NET.

_id

String

The immutable, unique identifier of the requested resource.

salesPrice.derivedPrice

Object

The calculated price with taxes applied (read-only).

listPrice.derivedPrice

Object

The calculated price with taxes applied (read-only).

manufacturerPrice.derivedPrice

Object

The calculated manufacturer’s suggested retail price with taxes applied (read-only).

description

String

The description of the product.

manufacturer

String

The manufacturer of the product.

visible

Boolean

Indicates if the product is visible in the online shop. Can be true or false.

onSale

Boolean

Indicates if the product is on offer. Can be true or false.

productIdentifiers

Array

The list of product identifiers.

productIdentifiers[].type

String

The product code to identify and classify the product. Can be EAN, UPC, ISBN, or MPN.

productIdentifiers[].value

String

The actual value of the product identifier.

essentialFeatures

String

The essential product properties of the product. Shown in the cart and checkout. In Germany mandatory field in online shops according to §312j Abs. 2 BGB (German Civil Code).

tags

Array

The tags assigned to a product.

taxClass

String

The tax class. Can be REGULAR, REDUCED, or EXEMPT.

shippingWeight

Number

The weight of the product including packaging in g.

maxOrderQuantity

Number

Displays how often this product can be ordered at maximum in one order.

shippingPeriod.minDays

Number

The minimum required days for shipping.

shippingPeriod.maxDays

Number

The maximum required days for shipping.

shippingPeriod.displayUnit

String

The unit to show the shipping period. Use DAYS or WEEKS.

shippingDimension.length

Number

The length of the product including packaging in mm.

shippingDimension.width

Number

The width of the product including packaging in mm.

shippingDimension.height

Number

The height of the product including packaging in mm.

refPrice

Object

The reference price of a product.

refPrice.refQuantity

Number

The reference quantity of the product.

refPrice.quantity

Number

The quantity in the product.

refPrice.unit

String

The unit of the quantity.

refPrice.price

Object

The price information scaled to a standardised base unit, according to the German base price regulation “Preisangabenverordnung” (PAngV), e.g. 1 l = 1.20 EUR. Is null if no reference amount is specified for the product.

variationAttributes

Array

The variation attributes with its values.

lastModifiedAt

String

The date and time the product was modified.

_embedded.availability

Object

The information about the availability of the product.

Links

Relation Description

product

The templated self link of the product. Current representation of the resource. See Hypermedia.

availability

The link to the information about product availability.

images

The link to the product image.

attachments

The product attachments resource.

default-image

The link to the default product image.

default-image-data

Download URL of the default image.

default-image-metadata

The URL to the image metadata of the default image.

google-shopping

The link to a product relation to Google Shopping.

amazon

The link to a product relation to Amazon.

attributes

The product properties resource.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 3637

{
  "_embedded" : {
    "availability" : {
      "availabilityState" : "IN_STOCK",
      "availableStock" : null,
      "stockThreshold" : null,
      "purchasable" : true,
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/801e9349-a1d7-4dc7-926b-073cb1e478b3/availability"
        }
      }
    }
  },
  "lastModifiedAt" : "2019-10-11T08:08:09.023",
  "sku" : "vino020",
  "salesPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 8.7,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 7.05,
      "taxRate" : 0.19
    }
  },
  "listPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 10.95,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 8.87,
      "taxRate" : 0.19
    }
  },
  "manufacturerPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 99.95,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 80.96,
      "taxRate" : 0.19
    }
  },
  "onSale" : true,
  "tags" : [ "Bestseller", "Red Wine", "Sale" ],
  "productIdentifiers" : [ {
    "type" : "EAN",
    "value" : "9780134308135"
  } ],
  "visible" : true,
  "taxClass" : "REGULAR",
  "shippingWeight" : 100,
  "maxOrderQuantity" : 6,
  "shippingDimension" : {
    "length" : 1500,
    "width" : 1000,
    "height" : 2000
  },
  "refPrice" : {
    "refQuantity" : 1,
    "unit" : "LITER",
    "quantity" : 0.75,
    "price" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 11.6,
      "derivedPrice" : {
        "taxModel" : "NET",
        "currency" : "EUR",
        "amount" : 9.4,
        "taxRate" : 0.19
      }
    }
  },
  "shippingPeriod" : {
    "minDays" : 2,
    "maxDays" : 4,
    "displayUnit" : "WEEKS"
  },
  "name" : "Rioja Castillo de Puerto (2013)",
  "description" : "Spain\nRioja Tempranillo",
  "manufacturer" : "Grape Vineyard",
  "essentialFeatures" : "Dry. 12% alcohol. Best vine variety.",
  "variationAttributes" : [ ],
  "_id" : "801e9349-a1d7-4dc7-926b-073cb1e478b3",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/801e9349-a1d7-4dc7-926b-073cb1e478b3"
    },
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/801e9349-a1d7-4dc7-926b-073cb1e478b3"
    },
    "availability" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/801e9349-a1d7-4dc7-926b-073cb1e478b3/availability"
    },
    "attributes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/801e9349-a1d7-4dc7-926b-073cb1e478b3/attributes"
    },
    "attachments" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/801e9349-a1d7-4dc7-926b-073cb1e478b3/attachments"
    },
    "images" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/801e9349-a1d7-4dc7-926b-073cb1e478b3/images"
    },
    "amazon" : {
      "href" : "http://amazon/amazon-products/801e9349-a1d7-4dc7-926b-073cb1e478b3"
    },
    "google-shopping" : {
      "href" : "http://google-shopping/google-products/801e9349-a1d7-4dc7-926b-073cb1e478b3"
    },
    "default-image" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/801e9349-a1d7-4dc7-926b-073cb1e478b3/default-image"
    },
    "default-image-data" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/photostore-2.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "templated" : true
    },
    "default-image-metadata" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/photostore-2.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998&download=no"
    }
  }
}

Show variation product details

A GET request is used to retrieve the details of a variation product.

Required scopes

prod:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/8eb08de0-fab1-49ff-bf53-1dda646cb03e' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

sku

Null

The stock keeping unit (SKU) corresponding to the product.

name

String

The name of the product.

visible

Boolean

Indicates if the product is visible in the online shop. Can be true or false.

tags

Array

The tags assigned to a product.

salesPrice

Object

The price of the product.

salesPrice.amount

Number

The amount of the sales price.

salesPrice.currency

String

The currency of the sales price.

salesPrice.taxModel

String

The tax model of the sales price. Can be GROSS or NET.

listPrice

Object

The previous price of a product that is currently on offer.

listPrice.amount

Number

The amount of the list price.

listPrice.currency

String

The currency of the list price.

listPrice.taxModel

String

The tax model of the list price. Can be GROSS or NET.

manufacturerPrice

Object

The manufacturer’s suggested retail price of the product.

manufacturerPrice.amount

Number

The amount of the manufacturer’s suggested retail price.

manufacturerPrice.currency

String

The currency of the manufacturer’s suggested retail price.

manufacturerPrice.taxModel

String

The tax model of the manufacturer’s suggested retail price. Can be GROSS or NET.

_id

String

The immutable, unique identifier of the requested resource.

salesPrice.derivedPrice

Object

The calculated price with taxes applied (read-only).

listPrice.derivedPrice

Object

The calculated price with taxes applied (read-only).

manufacturerPrice.derivedPrice

Object

The calculated manufacturer’s suggested retail price with taxes applied (read-only).

description

String

The description of the product.

manufacturer

String

The manufacturer of the product.

visible

Boolean

Indicates if the product is visible in the online shop. Can be true or false.

onSale

Boolean

Indicates if the product is on offer. Can be true or false.

productIdentifiers

Array

The list of product identifiers.

productIdentifiers[].type

String

The product code to identify and classify the product. Can be EAN, UPC, ISBN, or MPN.

productIdentifiers[].value

String

The actual value of the product identifier.

essentialFeatures

Null

The essential product properties of the product. Shown in the cart and checkout. In Germany mandatory field in online shops according to §312j Abs. 2 BGB (German Civil Code).

tags

Array

The tags assigned to a product.

taxClass

String

The tax class. Can be REGULAR, REDUCED, or EXEMPT.

shippingWeight

Null

The weight of the product including packaging in g.

maxOrderQuantity

Null

Displays how often this product can be ordered at maximum in one order.

shippingPeriod.minDays

Number

The minimum required days for shipping.

shippingPeriod.maxDays

Number

The maximum required days for shipping.

shippingPeriod.displayUnit

String

The unit to show the shipping period. Use DAYS or WEEKS.

shippingDimension.length

Number

The length of the product including packaging in mm.

shippingDimension.width

Number

The width of the product including packaging in mm.

shippingDimension.height

Number

The height of the product including packaging in mm.

refPrice

Null

The reference price of a product.

refPrice.refQuantity

Number

The reference quantity of the product.

refPrice.quantity

Number

The quantity in the product.

refPrice.unit

String

The unit of the quantity.

refPrice.price

Object

The price information scaled to a standardised base unit, according to the German base price regulation “Preisangabenverordnung” (PAngV), e.g. 1 l = 1.20 EUR. Is null if no reference amount is specified for the product.

variationAttributes

Array

The variation attributes with its values.

lastModifiedAt

String

The date and time the product was modified.

_embedded.availability

Object

The information about the availability of the product.

_embedded.salesPrice

Object

The price range of the variations of a variation product.

Links

Relation Description

product

The templated self link of the product. Current representation of the resource. See Hypermedia.

availability

The link to the information about product availability.

images

The link to the product image.

attachments

The product attachments resource.

default-image

The link to the default product image.

attributes

The product properties resource.

variations

The link to all variations of a product.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2948

{
  "_embedded" : {
    "availability" : {
      "availabilityState" : "NOT_AVAILABLE",
      "availableStock" : null,
      "stockThreshold" : null,
      "purchasable" : false,
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/8eb08de0-fab1-49ff-bf53-1dda646cb03e/availability"
        }
      }
    }
  },
  "lastModifiedAt" : "2019-10-11T08:09:14.979",
  "sku" : null,
  "salesPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 29.99,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 27.264,
      "taxRate" : 0.1
    }
  },
  "listPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 39.99,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 36.355,
      "taxRate" : 0.1
    }
  },
  "manufacturerPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 40.99,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 37.264,
      "taxRate" : 0.1
    }
  },
  "onSale" : true,
  "tags" : [ "Shirt", "Summer", "Sale" ],
  "productIdentifiers" : [ ],
  "visible" : true,
  "taxClass" : "REGULAR",
  "shippingWeight" : null,
  "maxOrderQuantity" : null,
  "shippingDimension" : {
    "length" : 2000,
    "width" : 750,
    "height" : 500
  },
  "refPrice" : null,
  "shippingPeriod" : {
    "minDays" : 3,
    "maxDays" : 5,
    "displayUnit" : "DAYS"
  },
  "name" : "Tony Highfinger, Poloshirt, Men",
  "description" : "100% cotton, regular fit, needs cold washing (max. 30°C), Fair Trade certified.",
  "manufacturer" : "Tony Highfinger",
  "essentialFeatures" : null,
  "variationAttributes" : [ {
    "displayName" : "size",
    "values" : [ "S", "M", "L", "XL" ]
  }, {
    "displayName" : "color",
    "values" : [ "Black", "White", "Grey" ]
  } ],
  "_id" : "8eb08de0-fab1-49ff-bf53-1dda646cb03e",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/8eb08de0-fab1-49ff-bf53-1dda646cb03e"
    },
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/8eb08de0-fab1-49ff-bf53-1dda646cb03e"
    },
    "availability" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/8eb08de0-fab1-49ff-bf53-1dda646cb03e/availability"
    },
    "attributes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/8eb08de0-fab1-49ff-bf53-1dda646cb03e/attributes"
    },
    "attachments" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/8eb08de0-fab1-49ff-bf53-1dda646cb03e/attachments"
    },
    "images" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/8eb08de0-fab1-49ff-bf53-1dda646cb03e/images"
    },
    "default-image" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/8eb08de0-fab1-49ff-bf53-1dda646cb03e/default-image"
    },
    "variations" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/8eb08de0-fab1-49ff-bf53-1dda646cb03e/variations"
    }
  }
}

Update product partially (json patch)

A PATCH request is used to update a product partially with json patch content type.

Required scopes

prod:u

Request body properties

Path Type Description

.[]

Array

A list of JSON Patch operations.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/ed7434ed-1025-4766-926c-41bfc5d7cd8b' -i -X PATCH \
    -H 'Content-Type: application/json-patch+json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '[ {
  "op" : "test",
  "path" : "/name",
  "value" : "Rioja Castillo de Puerto (2013)"
}, {
  "op" : "replace",
  "path" : "/name",
  "value" : "Castillo de Alba Rioja (2013)"
}, {
  "op" : "replace",
  "path" : "/manufacturer",
  "value" : "Mantecillia"
}, {
  "op" : "add",
  "path" : "/tags/-",
  "value" : "Spain"
}, {
  "op" : "remove",
  "path" : "/productIdentifiers"
} ]'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2961

{
  "_embedded" : {
    "availability" : {
      "availabilityState" : "IN_STOCK",
      "availableStock" : null,
      "stockThreshold" : null,
      "purchasable" : true,
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/ed7434ed-1025-4766-926c-41bfc5d7cd8b/availability"
        }
      }
    }
  },
  "lastModifiedAt" : "2019-10-11T08:07:54.458",
  "sku" : "vino020",
  "salesPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 8.7,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 7.9091,
      "taxRate" : 0.1
    }
  },
  "listPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 10.95,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 9.9545,
      "taxRate" : 0.1
    }
  },
  "manufacturerPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 99.95,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 90.864,
      "taxRate" : 0.1
    }
  },
  "onSale" : true,
  "tags" : [ "Bestseller", "Red Wine", "Sale", "Spain" ],
  "productIdentifiers" : null,
  "visible" : true,
  "taxClass" : "REGULAR",
  "shippingWeight" : 100,
  "maxOrderQuantity" : 6,
  "shippingDimension" : {
    "length" : 1500,
    "width" : 1000,
    "height" : 2000
  },
  "refPrice" : {
    "refQuantity" : 1,
    "unit" : "LITER",
    "quantity" : 0.75,
    "price" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 11.6,
      "derivedPrice" : {
        "taxModel" : "NET",
        "currency" : "EUR",
        "amount" : 10.545,
        "taxRate" : 0.1
      }
    }
  },
  "shippingPeriod" : {
    "minDays" : 2,
    "maxDays" : 4,
    "displayUnit" : "WEEKS"
  },
  "name" : "Castillo de Alba Rioja (2013)",
  "description" : "Spain\nRioja Tempranillo",
  "manufacturer" : "Mantecillia",
  "essentialFeatures" : "Dry. 12% alcohol. Best vine variety.",
  "variationAttributes" : [ ],
  "_id" : "ed7434ed-1025-4766-926c-41bfc5d7cd8b",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/ed7434ed-1025-4766-926c-41bfc5d7cd8b"
    },
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/ed7434ed-1025-4766-926c-41bfc5d7cd8b"
    },
    "availability" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/ed7434ed-1025-4766-926c-41bfc5d7cd8b/availability"
    },
    "attributes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/ed7434ed-1025-4766-926c-41bfc5d7cd8b/attributes"
    },
    "attachments" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/ed7434ed-1025-4766-926c-41bfc5d7cd8b/attachments"
    },
    "images" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/ed7434ed-1025-4766-926c-41bfc5d7cd8b/images"
    },
    "default-image" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/ed7434ed-1025-4766-926c-41bfc5d7cd8b/default-image"
    }
  }
}

Update product partially (json)

A PATCH request is used to update a product partially with json content type.

Required scopes

prod:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/c342534a-b156-40e4-861f-5f73d4a3549a' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{
  "name" : "Castillo de Alba Rioja (2013)",
  "description" : "Spain\nRioja",
  "manufacturer" : "Mantecillia"
}'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2995

{
  "_embedded" : {
    "availability" : {
      "availabilityState" : "IN_STOCK",
      "availableStock" : null,
      "stockThreshold" : null,
      "purchasable" : true,
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/c342534a-b156-40e4-861f-5f73d4a3549a/availability"
        }
      }
    }
  },
  "lastModifiedAt" : "2019-10-11T08:08:05.564",
  "sku" : "vino020",
  "salesPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 8.7,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 7.9091,
      "taxRate" : 0.1
    }
  },
  "listPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 10.95,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 9.9545,
      "taxRate" : 0.1
    }
  },
  "manufacturerPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 99.95,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 90.864,
      "taxRate" : 0.1
    }
  },
  "onSale" : true,
  "tags" : [ "Bestseller", "Red Wine", "Sale" ],
  "productIdentifiers" : [ {
    "type" : "EAN",
    "value" : "9780134308135"
  } ],
  "visible" : true,
  "taxClass" : "REGULAR",
  "shippingWeight" : 100,
  "maxOrderQuantity" : 6,
  "shippingDimension" : {
    "length" : 1500,
    "width" : 1000,
    "height" : 2000
  },
  "refPrice" : {
    "refQuantity" : 1,
    "unit" : "LITER",
    "quantity" : 0.75,
    "price" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 11.6,
      "derivedPrice" : {
        "taxModel" : "NET",
        "currency" : "EUR",
        "amount" : 10.545,
        "taxRate" : 0.1
      }
    }
  },
  "shippingPeriod" : {
    "minDays" : 2,
    "maxDays" : 4,
    "displayUnit" : "WEEKS"
  },
  "name" : "Castillo de Alba Rioja (2013)",
  "description" : "Spain\nRioja",
  "manufacturer" : "Mantecillia",
  "essentialFeatures" : "Dry. 12% alcohol. Best vine variety.",
  "variationAttributes" : [ ],
  "_id" : "c342534a-b156-40e4-861f-5f73d4a3549a",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/c342534a-b156-40e4-861f-5f73d4a3549a"
    },
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/c342534a-b156-40e4-861f-5f73d4a3549a"
    },
    "availability" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/c342534a-b156-40e4-861f-5f73d4a3549a/availability"
    },
    "attributes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/c342534a-b156-40e4-861f-5f73d4a3549a/attributes"
    },
    "attachments" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/c342534a-b156-40e4-861f-5f73d4a3549a/attachments"
    },
    "images" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/c342534a-b156-40e4-861f-5f73d4a3549a/images"
    },
    "default-image" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/c342534a-b156-40e4-861f-5f73d4a3549a/default-image"
    }
  }
}

Update variation product partially (json)

A PATCH request is used to update a variation product with all its variations partially with json content type.

variationAttributes can not be updated at the moment!

Required scopes

prod:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/40329522-7978-4a21-9e20-d3d08d250c0b' -i -X PATCH \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>' \
    -d '{
  "name" : "patched name",
  "description" : "patched description. <p><br></p><blockquote> <ol><li><strong>\n<h1></h1><h6></h6><em><a href=\"http://example.com\" target=\"_blank\"><u>this is my test html</u></a>\n</em></strong> </li></ol> </blockquote>",
  "variationAttributes" : [ {
    "displayName" : "size",
    "values" : [ "35", "36", "37" ]
  } ],
  "productIdentifiers" : null,
  "manufacturer" : "patched manufacturer",
  "salesPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 1.04,
    "derivedPrice" : null
  }
}'

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 3061

{
  "_embedded" : {
    "availability" : {
      "availabilityState" : "NOT_AVAILABLE",
      "availableStock" : null,
      "stockThreshold" : null,
      "purchasable" : false,
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/40329522-7978-4a21-9e20-d3d08d250c0b/availability"
        }
      }
    }
  },
  "lastModifiedAt" : "2019-10-11T08:09:22.246",
  "sku" : null,
  "salesPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 1.04,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 0.94545,
      "taxRate" : 0.1
    }
  },
  "listPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 39.99,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 36.355,
      "taxRate" : 0.1
    }
  },
  "manufacturerPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 40.99,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 37.264,
      "taxRate" : 0.1
    }
  },
  "onSale" : true,
  "tags" : [ "Shirt", "Summer", "Sale" ],
  "productIdentifiers" : null,
  "visible" : true,
  "taxClass" : "REGULAR",
  "shippingWeight" : null,
  "maxOrderQuantity" : null,
  "shippingDimension" : {
    "length" : 2000,
    "width" : 750,
    "height" : 500
  },
  "refPrice" : null,
  "shippingPeriod" : {
    "minDays" : 3,
    "maxDays" : 5,
    "displayUnit" : "DAYS"
  },
  "name" : "patched name",
  "description" : "patched description. <p><br></p><blockquote> <ol><li><strong>\n<h1></h1><h6></h6><em><a href=\"http://example.com\" target=\"_blank\"><u>this is my test html</u></a>\n</em></strong> </li></ol> </blockquote>",
  "manufacturer" : "patched manufacturer",
  "essentialFeatures" : null,
  "variationAttributes" : [ {
    "displayName" : "size",
    "values" : [ "S", "M", "L", "XL" ]
  }, {
    "displayName" : "color",
    "values" : [ "Black", "White", "Grey" ]
  } ],
  "_id" : "40329522-7978-4a21-9e20-d3d08d250c0b",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/40329522-7978-4a21-9e20-d3d08d250c0b"
    },
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/40329522-7978-4a21-9e20-d3d08d250c0b"
    },
    "availability" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/40329522-7978-4a21-9e20-d3d08d250c0b/availability"
    },
    "attributes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/40329522-7978-4a21-9e20-d3d08d250c0b/attributes"
    },
    "attachments" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/40329522-7978-4a21-9e20-d3d08d250c0b/attachments"
    },
    "images" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/40329522-7978-4a21-9e20-d3d08d250c0b/images"
    },
    "default-image" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/40329522-7978-4a21-9e20-d3d08d250c0b/default-image"
    },
    "variations" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/40329522-7978-4a21-9e20-d3d08d250c0b/variations"
    }
  }
}

Delete product

A DELETE request is used to delete a product or variation product. When a variation product is deleted, all its variations are deleted as well.

Required scopes

prod:d

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/8fc6da11-60ba-4c33-a400-e350ed114fcc' -i -X DELETE \
    -H 'Accept: application/hal+json' \
    -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 204 No Content

A search resource is used as an entry point for links to sub-resources offering dedicated product-related searches. Currently the following search options are offered:

Find a product by SKU

A GET request is used to search for a product by SKU.

Required scopes

prod:r

Request parameters

Parameter Description

sku

The stock keeping unit (SKU) corresponding to the product to search for.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/search/find-by-sku?sku=vino020' -i -X GET \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

sku

String

The stock keeping unit (SKU) corresponding to the product.

name

String

The name of the product.

visible

Boolean

Indicates if the product is visible in the online shop. Can be true or false.

tags

Array

The tags assigned to a product.

salesPrice

Object

The price of the product.

salesPrice.amount

Number

The amount of the sales price.

salesPrice.currency

String

The currency of the sales price.

salesPrice.taxModel

String

The tax model of the sales price. Can be GROSS or NET.

listPrice

Object

The previous price of a product that is currently on offer.

listPrice.amount

Number

The amount of the list price.

listPrice.currency

String

The currency of the list price.

listPrice.taxModel

String

The tax model of the list price. Can be GROSS or NET.

manufacturerPrice

Object

The manufacturer’s suggested retail price of the product.

manufacturerPrice.amount

Number

The amount of the manufacturer’s suggested retail price.

manufacturerPrice.currency

String

The currency of the manufacturer’s suggested retail price.

manufacturerPrice.taxModel

String

The tax model of the manufacturer’s suggested retail price. Can be GROSS or NET.

_id

String

The immutable, unique identifier of the requested resource.

salesPrice.derivedPrice

Object

The calculated price with taxes applied (read-only).

listPrice.derivedPrice

Object

The calculated price with taxes applied (read-only).

manufacturerPrice.derivedPrice

Object

The calculated manufacturer’s suggested retail price with taxes applied (read-only).

description

String

The description of the product.

manufacturer

String

The manufacturer of the product.

visible

Boolean

Indicates if the product is visible in the online shop. Can be true or false.

onSale

Boolean

Indicates if the product is on offer. Can be true or false.

productIdentifiers

Array

The list of product identifiers.

productIdentifiers[].type

String

The product code to identify and classify the product. Can be EAN, UPC, ISBN, or MPN.

productIdentifiers[].value

String

The actual value of the product identifier.

essentialFeatures

String

The essential product properties of the product. Shown in the cart and checkout. In Germany mandatory field in online shops according to §312j Abs. 2 BGB (German Civil Code).

tags

Array

The tags assigned to a product.

taxClass

String

The tax class. Can be REGULAR, REDUCED, or EXEMPT.

shippingWeight

Number

The weight of the product including packaging in g.

maxOrderQuantity

Number

Displays how often this product can be ordered at maximum in one order.

shippingPeriod.minDays

Number

The minimum required days for shipping.

shippingPeriod.maxDays

Number

The maximum required days for shipping.

shippingPeriod.displayUnit

String

The unit to show the shipping period. Use DAYS or WEEKS.

shippingDimension.length

Number

The length of the product including packaging in mm.

shippingDimension.width

Number

The width of the product including packaging in mm.

shippingDimension.height

Number

The height of the product including packaging in mm.

refPrice

Object

The reference price of a product.

refPrice.refQuantity

Number

The reference quantity of the product.

refPrice.quantity

Number

The quantity in the product.

refPrice.unit

String

The unit of the quantity.

refPrice.price

Object

The price information scaled to a standardised base unit, according to the German base price regulation “Preisangabenverordnung” (PAngV), e.g. 1 l = 1.20 EUR. Is null if no reference amount is specified for the product.

variationAttributes

Array

The variation attributes with its values.

lastModifiedAt

String

The date and time the product was modified.

_embedded.availability

Object

The information about the availability of the product.

Links

Relation Description

product

The templated self link of the product. Current representation of the resource. See Hypermedia.

availability

The link to the information about product availability.

images

The link to the product image.

attachments

The product attachments resource.

default-image

The link to the default product image.

default-image-data

Download URL of the default image.

default-image-metadata

The URL to the image metadata of the default image.

google-shopping

The link to a product relation to Google Shopping.

amazon

The link to a product relation to Amazon.

attributes

The product properties resource.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 3637

{
  "_embedded" : {
    "availability" : {
      "availabilityState" : "IN_STOCK",
      "availableStock" : null,
      "stockThreshold" : null,
      "purchasable" : true,
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/bac86c9b-0b89-485c-b07a-76c1910e1db0/availability"
        }
      }
    }
  },
  "lastModifiedAt" : "2019-10-11T08:08:00.723",
  "sku" : "vino020",
  "salesPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 8.7,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 7.05,
      "taxRate" : 0.19
    }
  },
  "listPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 10.95,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 8.87,
      "taxRate" : 0.19
    }
  },
  "manufacturerPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 99.95,
    "derivedPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 80.96,
      "taxRate" : 0.19
    }
  },
  "onSale" : true,
  "tags" : [ "Bestseller", "Red Wine", "Sale" ],
  "productIdentifiers" : [ {
    "type" : "EAN",
    "value" : "9780134308135"
  } ],
  "visible" : true,
  "taxClass" : "REGULAR",
  "shippingWeight" : 100,
  "maxOrderQuantity" : 6,
  "shippingDimension" : {
    "length" : 1500,
    "width" : 1000,
    "height" : 2000
  },
  "refPrice" : {
    "refQuantity" : 1,
    "unit" : "LITER",
    "quantity" : 0.75,
    "price" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 11.6,
      "derivedPrice" : {
        "taxModel" : "NET",
        "currency" : "EUR",
        "amount" : 9.4,
        "taxRate" : 0.19
      }
    }
  },
  "shippingPeriod" : {
    "minDays" : 2,
    "maxDays" : 4,
    "displayUnit" : "WEEKS"
  },
  "name" : "Rioja Castillo de Puerto (2013)",
  "description" : "Spain\nRioja Tempranillo",
  "manufacturer" : "Grape Vineyard",
  "essentialFeatures" : "Dry. 12% alcohol. Best vine variety.",
  "variationAttributes" : [ ],
  "_id" : "bac86c9b-0b89-485c-b07a-76c1910e1db0",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/bac86c9b-0b89-485c-b07a-76c1910e1db0"
    },
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/bac86c9b-0b89-485c-b07a-76c1910e1db0"
    },
    "availability" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/bac86c9b-0b89-485c-b07a-76c1910e1db0/availability"
    },
    "attributes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/bac86c9b-0b89-485c-b07a-76c1910e1db0/attributes"
    },
    "attachments" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/bac86c9b-0b89-485c-b07a-76c1910e1db0/attachments"
    },
    "images" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/bac86c9b-0b89-485c-b07a-76c1910e1db0/images"
    },
    "amazon" : {
      "href" : "http://amazon/amazon-products/bac86c9b-0b89-485c-b07a-76c1910e1db0"
    },
    "google-shopping" : {
      "href" : "http://google-shopping/google-products/bac86c9b-0b89-485c-b07a-76c1910e1db0"
    },
    "default-image" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/bac86c9b-0b89-485c-b07a-76c1910e1db0/default-image"
    },
    "default-image-data" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/photostore-2.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "templated" : true
    },
    "default-image-metadata" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/photostore-2.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998&download=no"
    }
  }
}

Find used tags

A GET request is used to search used tags by a starting string. All strings are sorted by usage, starting with the biggest.

Required scopes

prod:r

Request parameters

Parameter Description

startsWith

The search tags starting with this string.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/search/tags?startsWith=Best' -i -X GET \
    -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_embedded.tags

Array

The tags used with a product ordered by usage.

_links

Object

See Hypermedia

page

Object

See Pagination

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 330

{
  "_embedded" : {
    "tags" : [ {
      "tag" : "Bestseller",
      "count" : 1
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/search/tags?startsWith=Best&page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

List product search meta-information

A GET request will list the product meta information.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/search' -i -X GET \
    -H 'Authorization: Bearer <Access token>'

Links

Relation Description

find-by-sku

The link to find products by SKU.

tags

The link to find products by tags. Ordered by number of usage.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 371

{
  "_links" : {
    "tags" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/search/tags?startsWith={startsWith}",
      "templated" : true
    },
    "find-by-sku" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/search/find-by-sku?sku={sku}",
      "templated" : true
    },
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/search"
    }
  }
}

Show product details

A GET request is used to retrieve the details of a product.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/product-view/products/d9a24ecb-796d-4db5-a3b0-1796c025e939' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json'

Response body properties

Path Type Description

_id

String

The unique identifier of the product.

sku

String

The stock keeping unit (SKU) corresponding to the product.

name

String

The name of the product.

description

String

The description of the product.

salesPrice

Object

The price of the product.

listPrice

Object

The list price of the product, also known as the manufacturer’s suggested retail price or recommended retail price.

manufacturerPrice

Object

The list price of the product, also known as the manufacturer’s suggested retail price or recommended retail price.

onSale

Boolean

Indicates if the product is on offer. Can be true or false.

manufacturer

String

The manufacturer of the product.

essentialFeatures

String

The essential features of the product. Shown in the cart and checkout. In Germany mandatory field in online shops according to §312j Abs. 2 BGB (German Civil Code).

tags

Array

The tags assigned to a product.

shippingWeight

Number

The weight of the product including packaging in g.

shippingDimension

Object

The shipping dimensions of the product displayed in mm.

shippingDimension.length

Number

The length of the product including packaging in mm.

shippingDimension.width

Number

The width of the product including packaging in mm.

shippingDimension.height

Number

The height of the product including packaging in mm.

shippingPeriod

Object

The shipping period for this particular product.

attributes[]

Array

The product properties.

attributes[].key

String

The unique identifier of the product property.

attributes[].displayName

String

The displayed name of the product property.

attributes[].value

Varies

The value of the product property.

attributes[].format

Null

The format of the attribute value.

attributes[].formattedValue

Varies

The formatted value of the product property.

refPrice

Object

The price information scaled to a standardised base unit.

refPrice.refQuantity

Number

The reference quantity the product’s reference price is calculated on.

refPrice.quantity

Number

The actual quantity in the product.

refPrice.unit

String

The unit corresponding to the quanity.

refPrice.price

Object

The actual reference price.

availabilityState

String

The current availability state for the product. Can be IN_STOCK, LOW_STOCK, or OUT_OF_STOCK.

productIdentifiers[].type

String

The product code to identify and classify the product.

productIdentifiers[].value

String

The actual value of the product identifier.

listPriceText

String

The text that comes along with the list price.

_links

Object

See Hypermedia

Links

Relation Description

default-image-data

A link relation to the default image URL. See also Hypermedia.

additional-image-data

A link relation to additional image URLs. See also Hypermedia.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2580

{
  "_id" : "d9a24ecb-796d-4db5-a3b0-1796c025e939",
  "sku" : "vino020",
  "name" : "Rioja Castillo de Puerto (2013)",
  "manufacturer" : "Grape Vineyard",
  "salesPrice" : {
    "amount" : 8.7,
    "currency" : "EUR"
  },
  "onSale" : true,
  "listPrice" : {
    "amount" : 10.95,
    "currency" : "EUR"
  },
  "listPriceText" : "Old Price",
  "manufacturerPrice" : {
    "amount" : 99.95,
    "currency" : "EUR"
  },
  "refPrice" : {
    "refQuantity" : 1,
    "unit" : "LITER",
    "quantity" : 0.75,
    "price" : {
      "amount" : 11.6,
      "currency" : "EUR"
    }
  },
  "availabilityState" : "IN_STOCK",
  "shippingWeight" : 100,
  "shippingDimension" : {
    "length" : 1500,
    "width" : 1000,
    "height" : 2000
  },
  "productIdentifiers" : [ {
    "type" : "EAN",
    "value" : "501234567890"
  }, {
    "type" : "UPC",
    "value" : "425261"
  } ],
  "description" : "Spain\nRioja Tempranillo",
  "essentialFeatures" : "Dry. 12% alcohol. Best vine variety.",
  "tags" : [ "Bestseller", "Red Wine", "Sale" ],
  "attributes" : [ {
    "key" : "origin",
    "value" : "La Rioja",
    "displayName" : "origin",
    "format" : null,
    "formattedValue" : "La Rioja"
  }, {
    "key" : "type",
    "value" : "red",
    "displayName" : "type",
    "format" : null,
    "formattedValue" : "red"
  }, {
    "key" : "year",
    "value" : 2013.0,
    "displayName" : "year",
    "format" : null,
    "formattedValue" : 2013.0
  } ],
  "shippingPeriod" : {
    "minDays" : null,
    "maxDays" : 4,
    "displayUnit" : "WEEKS"
  },
  "_links" : {
    "default-image-data" : {
      "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/rioja-01.jpg?hash=e9a1ce5c0c6abfebec8fb1f6faf77dca7e6e7777{&width,height,upscale}",
      "templated" : true
    },
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-view/products/d9a24ecb-796d-4db5-a3b0-1796c025e939"
    },
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-view/products/d9a24ecb-796d-4db5-a3b0-1796c025e939"
    },
    "additional-image-data" : [ {
      "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/rioja-04.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281226000{&width,height,upscale}",
      "templated" : true
    }, {
      "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/rioja-02.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "templated" : true
    }, {
      "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/rioja-03.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225999{&width,height,upscale}",
      "templated" : true
    } ]
  }
}

Show variation product details

A GET request is used to retrieve the details of a variation product.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/product-view/products/3bf923df-9e18-4898-bc03-eb41d3a07fc7' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json'

Response body properties

Path Type Description

_id

String

The unique identifier of the product.

name

String

The name of the product.

salesPrice

Object

The price of the product.

minSalesPrice

Object

The minimum price of the product.

maxSalesPrice

Object

The maximum price of the product.

listPrice

Object

The list price of the product, also known as the manufacturer’s suggested retail price or recommended retail price.

manufacturerPrice

Object

The list price of the product, also known as the manufacturer’s suggested retail price or recommended retail price.

onSale

Boolean

Indicates if the product is on offer. Can be true or false.

listPriceText

Null

The text that comes along with the list price.

shippingWeight

Number

The weight of the product including packaging in g.

shippingDimension

Object

The shipping dimensions of the product displayed in mm.

shippingDimension.length

Number

The length of the product including packaging in mm.

shippingDimension.width

Number

The width of the product including packaging in mm.

shippingDimension.height

Number

The height of the product including packaging in mm.

refPrice

Object

The price information scaled to a standardised base unit.

refPrice.refQuantity

Number

The reference quantity the product’s reference price is calculated on.

refPrice.quantity

Number

The actual quantity in the product.

refPrice.unit

String

The unit corresponding to the quanity.

refPrice.price

Object

The actual reference price.

availabilityState

String

The current availability state for the product. Can be IN_STOCK, LOW_STOCK, or OUT_OF_STOCK.

variations

Array

The variations of the variation product.

variations[]._id

String

The unique identifier of the variation.

variations[].variationAttributeValues

Array

The concrete variation attributes for the variation.

variations[].variationAttributeValues[].displayName

String

The name of the variation attribute.

variations[].variationAttributeValues[].value

String

The value of the variation attribute.

description

String

The description of the product.

manufacturer

String

The manufacturer of the product.

essentialFeatures

String

The essential features of the product. Shown in the cart and checkout. In Germany mandatory field in online shops according to §312j Abs. 2 BGB (German Civil Code).

tags

Array

The tags assigned to a product.

attributes[]

Array

The product properties.

attributes[].key

String

The unique identifier of the product property.

attributes[].displayName

String

The displayed name of the product property.

attributes[].value

Varies

The value of the product property.

attributes[].format

Null

The format of the attribute value.

attributes[].formattedValue

Varies

The formatted value of the product property.

shippingPeriod

Object

The shipping period for this particular product.

variationAttributes

Array

The variation attributes with its values.

variationAttributes[].displayName

String

The name of the variation attribute.

variationAttributes[].values

Array

The values of the variation attribute.

productIdentifiers[].type

String

The product code to identify and classify the product.

productIdentifiers[].value

String

The actual value of the product identifier.

_links

Object

See Hypermedia

Links

Relation Description

default-image-data

A link relation to the default image URL. See also Hypermedia.

additional-image-data

A link relation to additional image URLs. See also Hypermedia.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2826

{
  "_id" : "3bf923df-9e18-4898-bc03-eb41d3a07fc7",
  "name" : "Rioja Castillo de Puerto (2013)",
  "manufacturer" : "Grape Vineyard",
  "salesPrice" : {
    "amount" : 8.7,
    "currency" : "EUR"
  },
  "minSalesPrice" : {
    "amount" : 8.7,
    "currency" : "EUR"
  },
  "maxSalesPrice" : {
    "amount" : 8.7,
    "currency" : "EUR"
  },
  "onSale" : true,
  "listPrice" : {
    "amount" : 10.95,
    "currency" : "EUR"
  },
  "listPriceText" : null,
  "manufacturerPrice" : {
    "amount" : 99.95,
    "currency" : "EUR"
  },
  "refPrice" : {
    "refQuantity" : 1,
    "unit" : "LITER",
    "quantity" : 0.75,
    "price" : {
      "amount" : 11.6,
      "currency" : "EUR"
    }
  },
  "availabilityState" : "IN_STOCK",
  "shippingWeight" : 100,
  "shippingDimension" : {
    "length" : 1500,
    "width" : 1000,
    "height" : 2000
  },
  "variations" : [ {
    "_id" : "3450d9e8-e06b-4fbc-8e06-b0032123a7c7",
    "variationAttributeValues" : [ {
      "displayName" : "Volume",
      "value" : "0.7l"
    } ]
  }, {
    "_id" : "49a979fb-450b-4d09-b340-a9af1f2d2f86",
    "variationAttributeValues" : [ {
      "displayName" : "Volume",
      "value" : "0.2l"
    } ]
  }, {
    "_id" : "f666c82f-c074-4a3d-ba6c-35385e86175c",
    "variationAttributeValues" : [ {
      "displayName" : "Volume",
      "value" : "1.5l"
    } ]
  } ],
  "variationAttributes" : [ {
    "displayName" : "Volume",
    "values" : [ "0.2l", "0.7l", "1.5l" ]
  } ],
  "productIdentifiers" : [ {
    "type" : "EAN",
    "value" : "501234567890"
  }, {
    "type" : "UPC",
    "value" : "425261"
  } ],
  "description" : "Spain\nRioja Tempranillo",
  "essentialFeatures" : "Dry. 12% alcohol. Best vine variety.",
  "tags" : [ "Bestseller", "High Protein", "Power Bar" ],
  "attributes" : [ {
    "key" : "origin",
    "value" : "La Rioja",
    "displayName" : "origin",
    "format" : null,
    "formattedValue" : "La Rioja"
  }, {
    "key" : "type",
    "value" : "red",
    "displayName" : "type",
    "format" : null,
    "formattedValue" : "red"
  }, {
    "key" : "year",
    "value" : 2013.0,
    "displayName" : "year",
    "format" : null,
    "formattedValue" : 2013.0
  } ],
  "shippingPeriod" : {
    "minDays" : 2,
    "maxDays" : 10,
    "displayUnit" : "days"
  },
  "_links" : {
    "default-image-data" : {
      "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/rioja-01.jpg?hash=e9a1ce5c0c6abfebec8fb1f6faf77dca7e6e7777{&width,height,upscale}",
      "templated" : true
    },
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-view/products/3bf923df-9e18-4898-bc03-eb41d3a07fc7"
    },
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-view/products/3bf923df-9e18-4898-bc03-eb41d3a07fc7"
    },
    "additional-image-data" : {
      "href" : "https://api-shop.beyondshop.cloud/api/testUri"
    }
  }
}

Show variation details

A GET request is used to retrieve the details of a variation.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/product-view/products/69f23b86-9d34-4d33-b60e-b2ab13f5f186' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json'

Response body properties

Path Type Description

_id

String

The unique identifier of the product.

name

String

The name of the product.

salesPrice

Object

The price of the product.

minSalesPrice

Object

The minimum price of the product.

maxSalesPrice

Object

The maximum price of the product.

listPrice

Object

The list price of the product, also known as the manufacturer’s suggested retail price or recommended retail price.

manufacturerPrice

Object

The list price of the product, also known as the manufacturer’s suggested retail price or recommended retail price.

onSale

Boolean

Indicates if the product is on offer. Can be true or false.

listPriceText

Null

The text that comes along with the list price.

shippingWeight

Number

The weight of the product including packaging in g.

shippingDimension

Object

The shipping dimensions of the product displayed in mm.

shippingDimension.length

Number

The length of the product including packaging in mm.

shippingDimension.width

Number

The width of the product including packaging in mm.

shippingDimension.height

Number

The height of the product including packaging in mm.

refPrice

Object

The price information scaled to a standardised base unit.

refPrice.refQuantity

Number

The reference quantity the product’s reference price is calculated on.

refPrice.quantity

Number

The actual quantity in the product.

refPrice.unit

String

The unit corresponding to the quanity.

refPrice.price

Object

The actual reference price.

availabilityState

String

The current availability state for the product. Can be IN_STOCK, LOW_STOCK, or OUT_OF_STOCK.

variations

Array

The variations of the variation product.

variations[]._id

String

The unique identifier of the variation.

variations[].variationAttributeValues

Array

The concrete variation attributes for the variation.

variations[].variationAttributeValues[].displayName

String

The name of the variation attribute.

variations[].variationAttributeValues[].value

String

The value of the variation attribute.

description

String

The description of the product.

manufacturer

String

The manufacturer of the product.

essentialFeatures

String

The essential features of the product. Shown in the cart and checkout. In Germany mandatory field in online shops according to §312j Abs. 2 BGB (German Civil Code).

tags

Array

The tags assigned to a product.

attributes[]

Array

The product properties.

attributes[].key

String

The unique identifier of the product property.

attributes[].displayName

String

The displayed name of the product property.

attributes[].value

Varies

The value of the product property.

attributes[].format

Null

The format of the attribute value.

attributes[].formattedValue

Varies

The formatted value of the product property.

shippingPeriod

Object

The shipping period for this particular product.

variationAttributes

Array

The variation attributes with its values.

variationAttributes[].displayName

String

The name of the variation attribute.

variationAttributes[].values

Array

The values of the variation attribute.

productIdentifiers[].type

String

The product code to identify and classify the product.

productIdentifiers[].value

String

The actual value of the product identifier.

_links

Object

See Hypermedia

variationAttributeValues

Array

The specific variation attributes for the selected variation.

variationAttributeValues[].displayName

String

The name of the variation attribute.

variationAttributeValues[].value

String

The value of the variation attribute.

sku

String

The stock keeping unit (SKU) corresponding to the variation.

Links

Relation Description

variation-product

A link relation to the variation product for a specific variation. See also Hypermedia.

default-image-data

A link relation to the default image URL. See also Hypermedia.

additional-image-data

A link relation to additional image URLs. See also Hypermedia.

Example response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 3584

{
  "_id" : "69f23b86-9d34-4d33-b60e-b2ab13f5f186",
  "sku" : "89d52c9a-1f45-4947-acf8-3265d258387b",
  "name" : "Rioja Castillo de Puerto (2013)",
  "manufacturer" : "Grape Vineyard",
  "salesPrice" : {
    "amount" : 8.7,
    "currency" : "EUR"
  },
  "minSalesPrice" : {
    "amount" : 8.7,
    "currency" : "EUR"
  },
  "maxSalesPrice" : {
    "amount" : 8.7,
    "currency" : "EUR"
  },
  "onSale" : true,
  "listPrice" : {
    "amount" : 10.95,
    "currency" : "EUR"
  },
  "listPriceText" : null,
  "manufacturerPrice" : {
    "amount" : 99.95,
    "currency" : "EUR"
  },
  "refPrice" : {
    "refQuantity" : 1,
    "unit" : "LITER",
    "quantity" : 0.75,
    "price" : {
      "amount" : 11.6,
      "currency" : "EUR"
    }
  },
  "availabilityState" : "IN_STOCK",
  "shippingWeight" : 100,
  "shippingDimension" : {
    "length" : 1500,
    "width" : 1000,
    "height" : 2000
  },
  "variations" : [ {
    "_id" : "69f23b86-9d34-4d33-b60e-b2ab13f5f186",
    "variationAttributeValues" : [ {
      "displayName" : "Volume",
      "value" : "0.2l"
    } ]
  }, {
    "_id" : "0574adae-5a9e-4c1b-a8f4-1c53e5351b19",
    "variationAttributeValues" : [ {
      "displayName" : "Volume",
      "value" : "0.7l"
    } ]
  }, {
    "_id" : "61d94adf-d964-4db0-ad22-f2e1c1461490",
    "variationAttributeValues" : [ {
      "displayName" : "Volume",
      "value" : "1.5l"
    } ]
  } ],
  "variationAttributes" : [ {
    "displayName" : "Volume",
    "values" : [ "0.2l", "0.7l", "1.5l" ]
  } ],
  "productIdentifiers" : [ {
    "type" : "EAN",
    "value" : "501234567890"
  }, {
    "type" : "UPC",
    "value" : "425261"
  } ],
  "description" : "Spain\nRioja Tempranillo",
  "essentialFeatures" : "Dry. 12% alcohol. Best vine variety.",
  "tags" : [ "Bestseller", "High Protein", "Power Bar" ],
  "attributes" : [ {
    "key" : "origin",
    "value" : "La Rioja",
    "displayName" : "origin",
    "format" : null,
    "formattedValue" : "La Rioja"
  }, {
    "key" : "type",
    "value" : "red",
    "displayName" : "type",
    "format" : null,
    "formattedValue" : "red"
  }, {
    "key" : "year",
    "value" : 2013.0,
    "displayName" : "year",
    "format" : null,
    "formattedValue" : 2013.0
  } ],
  "shippingPeriod" : {
    "minDays" : 2,
    "maxDays" : 10,
    "displayUnit" : "days"
  },
  "variationAttributeValues" : [ {
    "displayName" : "Volume",
    "value" : "0.2l"
  } ],
  "_links" : {
    "default-image-data" : {
      "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/rioja-01.jpg?hash=e9a1ce5c0c6abfebec8fb1f6faf77dca7e6e7777{&width,height,upscale}",
      "templated" : true
    },
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-view/products/69f23b86-9d34-4d33-b60e-b2ab13f5f186"
    },
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-view/products/69f23b86-9d34-4d33-b60e-b2ab13f5f186"
    },
    "additional-image-data" : [ {
      "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/rioja-02.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "templated" : true
    }, {
      "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/rioja-04.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281226000{&width,height,upscale}",
      "templated" : true
    }, {
      "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/rioja-03.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225999{&width,height,upscale}",
      "templated" : true
    } ],
    "variation-product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-view/products/9bca5a7d-c6b7-469c-bfb4-169c053dc13a"
    }
  }
}

List products

A GET request is used to list all products.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/product-view/products' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json'

Response body properties

Path Type Description

_embedded.products[]._id

String

The unique identifier of the product.

_embedded.products[].sku

String

The stock keeping unit (SKU) corresponding to the product.

_embedded.products[].salesPrice

Object

The price of the product.

_embedded.products[].listPrice

Object

The list price of the product, also known as the manufacturer’s suggested retail price or recommended retail price.

_embedded.products[].manufacturerPrice

Object

The list price of the product, also known as the manufacturer’s suggested retail price or recommended retail price.

_embedded.products[].onSale

Boolean

Indicates if the product is on offer. Can be true or false.

_embedded.products[].name

String

The name of the product.

_embedded.products[].manufacturer

String

The manufacturer of the product.

_embedded.products[].shippingWeight

Number

The weight of the product including packaging in g.

_embedded.products[].shippingDimension.length

Numbe