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 our brand new 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 new platform can already sign up for a beyondshop.

API Reference

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

Authentication

Create a JsonWebToken from Authorization Code

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

Request parameters

Parameter Description

grant_type

OAuth2 grant type. Use authorization_code for authorization code flow

code

The authorization code.

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 '05d09607-9f06-4118-8c9a-c70f432af4bc:n0d9sk57kapn34ea37pvkv0fn5' -X POST -d 'grant_type=authorization_code&code=nLgTzg'

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 to each request. Refer to RFC 7519.

refresh_token

String

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

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/json;charset=UTF-8
Content-Length: 1554

{
  "access_token" : "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.eyJ1c2VyX25hbWUiOiJ1c2VyIiwic2NvcGUiOlsidXNlcjpyIl0sInRlbmFudElkIjoxMzUsImV4cCI6MTUxODc0NTIxMywiaWF0IjoxNTE4NzAyMDEzLCJqdGkiOiJhMjRhOTVkZC1hNWI2LTQ0YjItYWRiNS1lMWI2N2Y0YTRhY2UiLCJjbGllbnRfaWQiOiIwNWQwOTYwNy05ZjA2LTQxMTgtOGM5YS1jNzBmNDMyYWY0YmMifQ.mb-yHeCiaazvuxmbXT0m6A0B7ldlQz7JwMeR85d1lddSUfV3AzqIT0qUAT4OskNNqp_WJQ69U5TcbfA3KZLFO3S7tL3sm-fLvwjyn3FDOnitYf627HB8m-skhiM3bZSXA3dmok_f6FRg-RNfjMfIiLlMMqf9HERIGQAChrOB1fja2mkAkzVV98O9o83E_0duQUcvNKKnjgxXK3tYW0wv2vXNBskGbNGfj7ONyGBSEwpBg4mobtW2XKuT1cftTtdfyJ-REaq70ZrhTGrSQZ3MfV1WETgwF0-iTDOP5N5e3_areGq8ih7Fs8a9Gzh_FkKi1fTSfjVMX2XlyO5z_pp8-A",
  "token_type" : "bearer",
  "refresh_token" : "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.eyJ1c2VyX25hbWUiOiJ1c2VyIiwic2NvcGUiOlsidXNlcjpyIl0sImF0aSI6ImEyNGE5NWRkLWE1YjYtNDRiMi1hZGI1LWUxYjY3ZjRhNGFjZSIsInRlbmFudElkIjoxMzUsImV4cCI6MTUyMTI5NDAxMywiaWF0IjoxNTE4NzAyMDEzLCJqdGkiOiJlZTZkODE1Ny1hMjk4LTRlZTctYTA5Ni0wN2MwNWFiNWEwZTkiLCJjbGllbnRfaWQiOiIwNWQwOTYwNy05ZjA2LTQxMTgtOGM5YS1jNzBmNDMyYWY0YmMifQ.YMadpcMeCDDdWYbHXMYW6b1Qi8cSz9YutCJLFzaxNjliDUVumntgevHxMCBH4JuH5UxSqvef6Gs2MH-xFdOt9SJhzGraXQ0GgkB7d_cqefbWPyZ4tw-6loYQ-3r_dHOX4oavZhE0yJgHrcXS8qt7W1pgCYLNboKl-Z903L7xozeEfZXkwYh7WnY5qYYMsDRLNMugcgnxtrZo8XW5sBWONjP4nFGQpwVu0IEi2S9ud1Fadqeg3dnKsMrOIawTu_4zAI5W2rbRQG_9y3YqmUjcu6froMcFY70-RenIK007E_JPqmkAPx8aQ31Fvzx_mruTCIvkFPF9UDonwiMtx2rViA",
  "expires_in" : 43199,
  "scope" : "user:r",
  "tenantId" : 135,
  "iat" : 1518702013,
  "jti" : "a24a95dd-a5b6-44b2-adb5-e1b67f4a4ace"
}

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. Used to obtain additional access tokens to prolong the authorization to access resources. Use refresh_token here.

client_id

The client identifier issued to the client during the registration process. Refer to RFC 6749.

refresh_token

The token that can be used to obtain a renewed access token when the current token has expired.

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:ae514e9b-3cd3-4e39-a753-41ac9d61b627' -X POST -d 'grant_type=refresh_token&client_id=sample-client&refresh_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.eyJ1c2VyX25hbWUiOiJ1c2VyIiwic2NvcGUiOlsicHJvZDpyYyJdLCJhdGkiOiJhZjZiZTg4Mi0yMDY4LTRjYjItOTFlMi02NDBjMjJiYjdiYzMiLCJ0ZW5hbnRJZCI6MTQzOCwiZXhwIjoxNTIxMjk0MDAyLCJpYXQiOjE1MTg3MDIwMDIsInVzZXJJZCI6ImIxZTAxOWIxLTQ3MjUtNDA0ZC05YjQyLTU3Y2FlN2JjNmRiMCIsImp0aSI6IjFlMTUwNTZjLTBjZWMtNDZlMi1hMzhjLWExODY0NjZmNGY1MCIsImNsaWVudF9pZCI6InNhbXBsZS1jbGllbnQiLCJ1c2VybmFtZSI6InVzZXIifQ.TSoazhV91bPqLsWfbJBqE3nQ3WLXTquDIMlGlziJMLi6bmD6cEHlepRLVjFkTxo9Qq-kZu9lqGFlg8HsMmBjLb_a_KM9fhGQ7HjTIKUx4N6b7OXVG9gZQLtmwE7gaEN3yAVIsj_SK5Nr-gcagGXQXvfZurIo3jU3xdMi9KPUqyAnY8Kk39Kg_lBLB74VEQWwawtPqEneKyw5O-lrbLDaHUo8ezlwLXI9YuribJUk1NVtN0PhO2Qxlm3oQkMlbNvBUmx7rEBkbmrmsimmhs27S9sG1SEXRyASCQSti9XNOVMp1B3K8yFm804jdlVO221v99SJjCMbmhlFq3LcKyqzZw'

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 to each request. Refer to RFC 7519.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/json;charset=UTF-8
Content-Length: 1753

{
  "access_token" : "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.eyJ1c2VyX25hbWUiOiJ1c2VyIiwic2NvcGUiOlsicHJvZDpyYyJdLCJ0ZW5hbnRJZCI6MTQzOCwiZXhwIjoxNTE4OTYxMjAyLCJpYXQiOjE1MTg3MDIwMDIsInVzZXJJZCI6ImIxZTAxOWIxLTQ3MjUtNDA0ZC05YjQyLTU3Y2FlN2JjNmRiMCIsImp0aSI6IjY5N2EwNWZiLTM1MTMtNGIyMC04MTRmLWJkYTQyYzEwMTEwYyIsImNsaWVudF9pZCI6InNhbXBsZS1jbGllbnQiLCJ1c2VybmFtZSI6InVzZXIifQ.eT1h4HiYRK5YLFvg6GPswpXmfv8KRhdH34bslCaoRb39NdzrwwvFAR2UEZdyDtl5qdqWHTRR2n2hr015qW751QhL70Uh4v0i2PrCHii5S-KoJTGy0RzkJBrMdP80xt2476tUGglrfK_je0v1TpSN0F6fSLzN6AjFWT7njV2i8ZnYNbh3QGNbvaCSoJ_YyqAYtyW4F2TTBzJr9bzbkKgHWg4vY5Y3JOAS3UI-D49eDysjSdhj4krwhuqx5CVhlaKTaiAIwJvvGiW_IFeKqgx-UzJf8MnYwO1WMhIvEMCmCGm970whSX-WKhyVUCPEazYeT1tiIlcPraf75Ry9vpAQHw",
  "token_type" : "bearer",
  "refresh_token" : "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.eyJ1c2VyX25hbWUiOiJ1c2VyIiwic2NvcGUiOlsicHJvZDpyYyJdLCJhdGkiOiI2OTdhMDVmYi0zNTEzLTRiMjAtODE0Zi1iZGE0MmMxMDExMGMiLCJ0ZW5hbnRJZCI6MTQzOCwiZXhwIjoxNTIxMjk0MDAyLCJpYXQiOjE1MTg3MDIwMDIsInVzZXJJZCI6ImIxZTAxOWIxLTQ3MjUtNDA0ZC05YjQyLTU3Y2FlN2JjNmRiMCIsImp0aSI6IjFlMTUwNTZjLTBjZWMtNDZlMi1hMzhjLWExODY0NjZmNGY1MCIsImNsaWVudF9pZCI6InNhbXBsZS1jbGllbnQiLCJ1c2VybmFtZSI6InVzZXIifQ.e6IdQq6oh1v2YIj5IO5le4UmiiN35uCR_nxwLE0R6xz6iC3LnimPR1OZchcR6_Krz5laWrSi7wWWkl9inpd5eEMP2_XX-ia2tvu-3aCs7YV2FcDQDkCjSIu5Z5QvKHNDJaXumyAQ9ZtDfVKF04KSjutgc6uZqd2Nd5uW2CMjKHYJfGcwY1LW-k-nVUdQlMtPsE1OlLUhBAURMxBkxKx47GNzVtOxnNpQynLz2HJvtw0fbskMRM23B_5PtZKTNjB3qDsQBkDE_qzevu42bqBqkpnrW98CW7_-u4LwY-p_pRNtozd3j4Y3yfIS0c9HbX4HlpwPOF-zqC8y88cWpN7hUw",
  "expires_in" : 259199,
  "scope" : "prod:rc",
  "tenantId" : 1438,
  "iat" : 1518702002,
  "userId" : "b1e019b1-4725-404d-9b42-57cae7bc6db0",
  "username" : "user",
  "jti" : "697a05fb-3513-4b20-814f-bda42c10110c"
}

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. Used as an authorization grant to request access to protected resources. Use client_credentials for client credentials flow. Refer to RFC 6749.

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 'clientId1: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 to each request. Refer to RFC 7519.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/json;charset=UTF-8
Content-Length: 773

{
  "access_token" : "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEifQ.eyJzY29wZSI6WyJwcm9kOmNyIl0sInRlbmFudElkIjoxNDM4LCJleHAiOjE1MTg3NDUyMDMsImlhdCI6MTUxODcwMjAwMywianRpIjoiYzAyYTZjYTctMDg5ZS00NDQzLTg2NDEtZjBlMTU3MzVmNmFhIiwiY2xpZW50X2lkIjoiY2xpZW50SWQxIn0.UIumqZORiqtut8OXxnvJkmLzVONM5KmLFC91T1laaAzeZ0bbUn6H9vm3KohwC8gUmA_Y_QEfbs163WHLvbTVKEcu2Z1q-84BuPse5OwKzUqn6RB2tOLAUH2Vhm8asb_QA_Vu7i5HbB3NyqCuCPas1B8FaVeqR5l9Jf4Nt3oc4O9Lb6-UHwpOUDVW_iCveQJ_r8JZwTH85TlINBrtsuh7NnJwBT4K0qnb6vdYedJaTFRjel1FSOeVC2VpfT2MTSbaouXE7g4a3LsLhzG0HIvvrjHpPgToiOR7oYoH1EdJq-2DD_53glcJvsxEqlIan-M2jlqosoZG7Qoc5n_CuZKWDg",
  "token_type" : "bearer",
  "expires_in" : 43199,
  "scope" : "prod:cr",
  "tenantId" : 1438,
  "iat" : 1518702003,
  "jti" : "c02a6ca7-089e-4443-8641-f0e15735f6aa"
}

Carts

The carts resources is used to manage the carts of a shop.

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 'Content-Type: application/json' -H 'Accept: application/hal+json' -d '{}'

Example response

HTTP/1.1 201 Created
Location: https://api-shop.beyondshop.cloud/api/carts/04e6a99c-fcb3-4c2d-b309-7997f34cab20
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 4410

{
  "lineItems" : [ ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "shipping-method" : {
        "name" : "Standard Shipping 1",
        "description" : "Standard Shipping",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : null,
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 16.95
        },
        "weightBasedPrice" : null,
        "_id" : "60873cef-e5ad-422c-8878-af9026211fe7",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/8b6c5e7b-d78b-4fbe-ae22-61c5282ed33a/shipping-methods/60873cef-e5ad-422c-8878-af9026211fe7"
          }
        }
      }
    }
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "payment-method" : {
        "name" : "PayPal",
        "description" : "Pay with PayPal",
        "officialName" : "PayPal",
        "officialDescription" : "Pay with PayPal",
        "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,
        "activatable" : true,
        "_id" : "be0ba4e0-23c2-4053-a5a6-dd7c6223ec7f",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/be0ba4e0-23c2-4053-a5a6-dd7c6223ec7f"
          },
          "deactivate-payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/be0ba4e0-23c2-4053-a5a6-dd7c6223ec7f/deactivate"
          }
        }
      }
    }
  },
  "billingAddress" : null,
  "shippingAddress" : null,
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 18.95
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 18.95
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 18.95
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "taxes" : [ ],
  "taxable" : true,
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "weight" : 0,
  "checkoutState" : {
    "shippingMethodValid" : true,
    "shippingMethodSelectable" : true,
    "paymentMethodValid" : true,
    "paymentMethodSelectable" : true,
    "billingAddressSet" : false,
    "priceValidToOrder" : true,
    "paymentTransactionStatus" : "NO_APPROVAL_NEEDED",
    "readyToOrder" : false
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/04e6a99c-fcb3-4c2d-b309-7997f34cab20"
    },
    "line-items" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/04e6a99c-fcb3-4c2d-b309-7997f34cab20/line-items"
    },
    "shipping-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/04e6a99c-fcb3-4c2d-b309-7997f34cab20/shipping-methods"
    },
    "shipping-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/04e6a99c-fcb3-4c2d-b309-7997f34cab20/shipping-methods/default"
    },
    "shipping-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/04e6a99c-fcb3-4c2d-b309-7997f34cab20/shipping-methods/current"
    },
    "payment-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/04e6a99c-fcb3-4c2d-b309-7997f34cab20/payment-methods"
    },
    "payment-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/04e6a99c-fcb3-4c2d-b309-7997f34cab20/payment-methods/default"
    },
    "payment-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/04e6a99c-fcb3-4c2d-b309-7997f34cab20/payment-methods/current"
    },
    "billing-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/04e6a99c-fcb3-4c2d-b309-7997f34cab20/billing-address"
    },
    "shipping-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/04e6a99c-fcb3-4c2d-b309-7997f34cab20/shipping-address"
    }
  },
  "_id" : "04e6a99c-fcb3-4c2d-b309-7997f34cab20"
}

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/45915d41-2fd0-4dec-9a28-60e0e9117bd6' -i -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.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._links.product

Object

The link to the product.

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

Object

Download URL of the default image.

lineItems[].quantity.value

Number

The value of the quantity.

lineItems[].quantity.unit

String

The unit of the quantity.

lineItems[].quantityInt

Number

The value of the quantity.

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.

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.

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.

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 mininmum value of the cart so that this payment method can be used.

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 price is valid to create an order. Can be true or false.

checkoutState.paymentTransactionStatus

String

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

Links

Relation Description

line-items

The link to the line items.

payment-method-available

The link to the payment methods available for this cart.

payment-method-default

The link to the default payment method.

payment-method-current

The link to the current payment method.

shipping-method-available

The link to the shipping methods available for this cart.

shipping-method-default

The link to the default shipping method.

shipping-method-current

The link to the current shipping method.

shipping-address

The link to the shipping address.

billing-address

The link to the billing address.

place-order

The link to place an order. Only available on carts that are ready to order.

Example response

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

{
  "lineItems" : [ {
    "_type" : "PRODUCT",
    "_id" : "ff738226-ad16-4cfb-93c2-51486c23e64f",
    "_ref" : "0faa3ceb-51f7-49f7-8dc8-a43cb3710799",
    "name" : "Decorative Sand (2 kg Jumbo Pack)",
    "quantity" : {
      "value" : 1,
      "unit" : "PIECE"
    },
    "singleItemPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 42.0084
    },
    "lineItemPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 42.0084
    },
    "_embedded" : {
      "product" : {
        "_id" : "0faa3ceb-51f7-49f7-8dc8-a43cb3710799",
        "sku" : "1018",
        "essentialFeatures" : "Not suitable for children under the age of 8.",
        "_links" : {
          "product" : {
            "href" : "https://api-shop.beyondshop.cloud/api/product-view/products/0faa3ceb-51f7-49f7-8dc8-a43cb3710799?locale=de-DE"
          },
          "default-image-data" : {
            "href" : "https://api-shop.beyondshop.cloud/api/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
            "templated" : true
          }
        }
      }
    },
    "quantityInt" : 1,
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 7.9816
    },
    "_links" : {
      "self" : {
        "href" : "https://api-shop.beyondshop.cloud/api/carts/45915d41-2fd0-4dec-9a28-60e0e9117bd6/line-items/ff738226-ad16-4cfb-93c2-51486c23e64f"
      }
    }
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 50
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.0,
      "currency" : "EUR",
      "amount" : 0
    } ],
    "_embedded" : {
      "shipping-method" : {
        "name" : "Express",
        "description" : "Shipping overnight, delivery on the next day.",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : {
          "currency" : "EUR",
          "amount" : 1000
        },
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 50
        },
        "weightBasedPrice" : null,
        "_id" : "18fce214-b6c9-4eb5-a96a-d890d7b2b193",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/e1878ccc-79d3-4afd-b27c-506ae5d63f64/shipping-methods/18fce214-b6c9-4eb5-a96a-d890d7b2b193"
          }
        }
      }
    }
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.0,
      "currency" : "EUR",
      "amount" : 0
    } ],
    "_embedded" : {
      "payment-method" : {
        "name" : "PayPal",
        "description" : "Pay with PayPal",
        "officialName" : "PayPal",
        "officialDescription" : "Pay with PayPal",
        "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,
        "activatable" : true,
        "_id" : "7be7125e-0d04-4db5-92a9-ecf41cd30342",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/7be7125e-0d04-4db5-92a9-ecf41cd30342"
          },
          "deactivate-payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/7be7125e-0d04-4db5-92a9-ecf41cd30342/deactivate"
          }
        }
      }
    }
  },
  "billingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : null,
    "title" : "",
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "Erdgeschoss",
    "addressExtension" : "",
    "postalCode" : "20999",
    "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", "20999 Alsterwasser" ],
    "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" : "",
    "postalCode" : "20999",
    "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", "20999 Alsterwasser" ],
    "doorCode" : "0815"
  },
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 42.0084
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 94.0084
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 94.0084
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 94.0084
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "taxes" : [ {
    "taxClass" : "REGULAR",
    "taxRate" : 0.0,
    "currency" : "EUR",
    "amount" : 0
  } ],
  "taxable" : true,
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "weight" : 2000,
  "checkoutState" : {
    "shippingMethodValid" : true,
    "shippingMethodSelectable" : true,
    "paymentMethodValid" : true,
    "paymentMethodSelectable" : true,
    "billingAddressSet" : true,
    "priceValidToOrder" : true,
    "paymentTransactionStatus" : "NO_APPROVAL_NEEDED",
    "readyToOrder" : true
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/45915d41-2fd0-4dec-9a28-60e0e9117bd6"
    },
    "line-items" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/45915d41-2fd0-4dec-9a28-60e0e9117bd6/line-items"
    },
    "shipping-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/45915d41-2fd0-4dec-9a28-60e0e9117bd6/shipping-methods"
    },
    "shipping-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/45915d41-2fd0-4dec-9a28-60e0e9117bd6/shipping-methods/default"
    },
    "shipping-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/45915d41-2fd0-4dec-9a28-60e0e9117bd6/shipping-methods/current"
    },
    "payment-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/45915d41-2fd0-4dec-9a28-60e0e9117bd6/payment-methods"
    },
    "payment-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/45915d41-2fd0-4dec-9a28-60e0e9117bd6/payment-methods/default"
    },
    "payment-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/45915d41-2fd0-4dec-9a28-60e0e9117bd6/payment-methods/current"
    },
    "billing-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/45915d41-2fd0-4dec-9a28-60e0e9117bd6/billing-address"
    },
    "shipping-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/45915d41-2fd0-4dec-9a28-60e0e9117bd6/shipping-address"
    },
    "place-order" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/45915d41-2fd0-4dec-9a28-60e0e9117bd6/order"
    }
  },
  "_id" : "45915d41-2fd0-4dec-9a28-60e0e9117bd6"
}

Delete cart

A DELETE request is used to remove the cart.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/4ad5dfbc-1b8a-4dc4-a31e-5edb3f0aa8be' -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. The 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

customerComment

String

An optional comment from the customer regarding the order.

salesChannel

String

The sales channel for this order.

marketingChannel

String

The marketing channel for this order.

marketingSubchannel

String

The marketing subchannel for this order.

testOrder

Boolean

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

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/756cb95e-e5d7-4bcd-affb-2d13f5bfdd88/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}'

Example response

HTTP/1.1 202 Accepted
Location: https://api-shop.beyondshop.cloud/api/order/orders/search/find-by-cart-id?cartId=756cb95e-e5d7-4bcd-affb-2d13f5bfdd88

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).

quantityInt

Number

The value of the quantity.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/33faab4f-b70d-436a-a68e-6e9007a42711/line-items' -i -X POST -H 'Content-Type: application/json' -d '{"_type":"PRODUCT","_ref":"ad8efa16-aa83-4bc9-a257-da00667717ac","quantityInt":1}'

Example response

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

{
  "lineItems" : [ {
    "_type" : "PRODUCT",
    "_id" : "6ae8ebe1-e1ef-4e10-85f0-f99749a9c64b",
    "_ref" : "ad8efa16-aa83-4bc9-a257-da00667717ac",
    "name" : "Decorative Sand (2 kg Jumbo Pack)",
    "quantity" : {
      "value" : 1,
      "unit" : "PIECE"
    },
    "singleItemPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 42.0084
    },
    "lineItemPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 42.0084
    },
    "_embedded" : {
      "product" : {
        "_id" : "ad8efa16-aa83-4bc9-a257-da00667717ac",
        "sku" : "1018",
        "essentialFeatures" : "Not suitable for children under the age of 8.",
        "_links" : {
          "product" : {
            "href" : "https://api-shop.beyondshop.cloud/api/product-view/products/ad8efa16-aa83-4bc9-a257-da00667717ac?locale=de-DE"
          },
          "default-image-data" : {
            "href" : "https://api-shop.beyondshop.cloud/api/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
            "templated" : true
          }
        }
      }
    },
    "quantityInt" : 1,
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 7.981596
    },
    "_links" : {
      "self" : {
        "href" : "https://api-shop.beyondshop.cloud/api/carts/33faab4f-b70d-436a-a68e-6e9007a42711/line-items/6ae8ebe1-e1ef-4e10-85f0-f99749a9c64b"
      }
    }
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.0,
      "currency" : "EUR",
      "amount" : 0
    } ],
    "_embedded" : {
      "shipping-method" : {
        "name" : "Standard Shipping 1",
        "description" : "Standard Shipping",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : null,
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 16.95
        },
        "weightBasedPrice" : null,
        "_id" : "92261898-8e4d-4166-bb41-7c903c5ffeec",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/e6d833cd-52f7-4593-bb1f-fd356de197f7/shipping-methods/92261898-8e4d-4166-bb41-7c903c5ffeec"
          }
        }
      }
    }
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.0,
      "currency" : "EUR",
      "amount" : 0
    } ],
    "_embedded" : {
      "payment-method" : {
        "name" : "PayPal",
        "description" : "Pay with PayPal",
        "officialName" : "PayPal",
        "officialDescription" : "Pay with PayPal",
        "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,
        "activatable" : true,
        "_id" : "d964fc06-7615-4277-b3e3-a18dbd908191",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/d964fc06-7615-4277-b3e3-a18dbd908191"
          },
          "deactivate-payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/d964fc06-7615-4277-b3e3-a18dbd908191/deactivate"
          }
        }
      }
    }
  },
  "billingAddress" : null,
  "shippingAddress" : null,
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 42.0084
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 60.9584
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 60.9584
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 60.9584
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "taxes" : [ {
    "taxClass" : "REGULAR",
    "taxRate" : 0.0,
    "currency" : "EUR",
    "amount" : 0
  } ],
  "taxable" : true,
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "weight" : 2000,
  "checkoutState" : {
    "shippingMethodValid" : true,
    "shippingMethodSelectable" : true,
    "paymentMethodValid" : true,
    "paymentMethodSelectable" : true,
    "billingAddressSet" : false,
    "priceValidToOrder" : true,
    "paymentTransactionStatus" : "NO_APPROVAL_NEEDED",
    "readyToOrder" : false
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/33faab4f-b70d-436a-a68e-6e9007a42711"
    },
    "line-items" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/33faab4f-b70d-436a-a68e-6e9007a42711/line-items"
    },
    "shipping-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/33faab4f-b70d-436a-a68e-6e9007a42711/shipping-methods"
    },
    "shipping-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/33faab4f-b70d-436a-a68e-6e9007a42711/shipping-methods/default"
    },
    "shipping-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/33faab4f-b70d-436a-a68e-6e9007a42711/shipping-methods/current"
    },
    "payment-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/33faab4f-b70d-436a-a68e-6e9007a42711/payment-methods"
    },
    "payment-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/33faab4f-b70d-436a-a68e-6e9007a42711/payment-methods/default"
    },
    "payment-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/33faab4f-b70d-436a-a68e-6e9007a42711/payment-methods/current"
    },
    "billing-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/33faab4f-b70d-436a-a68e-6e9007a42711/billing-address"
    },
    "shipping-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/33faab4f-b70d-436a-a68e-6e9007a42711/shipping-address"
    }
  },
  "_id" : "33faab4f-b70d-436a-a68e-6e9007a42711"
}

Replace line items

A PUT request is used to replace the current line items of 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/82dbccfe-ce35-450f-845e-d6c487f226fa/line-items' -i -X PUT -H 'Content-Type: application/json' -d '[{"_type":"PRODUCT","_ref":"0796fdea-5f3b-45f6-8b24-d2171a847fff","quantityInt":1}]'

Example response

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

{
  "lineItems" : [ {
    "_type" : "PRODUCT",
    "_id" : "62df1f18-ebcc-4dbf-a90e-db1fbbb5cd19",
    "_ref" : "0796fdea-5f3b-45f6-8b24-d2171a847fff",
    "name" : "Decorative Sand (2 kg Jumbo Pack)",
    "quantity" : {
      "value" : 1,
      "unit" : "PIECE"
    },
    "singleItemPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 42.0084
    },
    "lineItemPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 42.0084
    },
    "_embedded" : {
      "product" : {
        "_id" : "0796fdea-5f3b-45f6-8b24-d2171a847fff",
        "sku" : "1018",
        "essentialFeatures" : "Not suitable for children under the age of 8.",
        "_links" : {
          "product" : {
            "href" : "https://api-shop.beyondshop.cloud/api/product-view/products/0796fdea-5f3b-45f6-8b24-d2171a847fff?locale=de-DE"
          },
          "default-image-data" : {
            "href" : "https://api-shop.beyondshop.cloud/api/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
            "templated" : true
          }
        }
      }
    },
    "quantityInt" : 1,
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 7.981596
    },
    "_links" : {
      "self" : {
        "href" : "https://api-shop.beyondshop.cloud/api/carts/82dbccfe-ce35-450f-845e-d6c487f226fa/line-items/62df1f18-ebcc-4dbf-a90e-db1fbbb5cd19"
      }
    }
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.0,
      "currency" : "EUR",
      "amount" : 0
    } ],
    "_embedded" : {
      "shipping-method" : {
        "name" : "Standard Shipping 1",
        "description" : "Standard Shipping",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : null,
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 16.95
        },
        "weightBasedPrice" : null,
        "_id" : "205c72ab-859c-477b-b933-41b7ea0262a7",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/6bbdc2ad-17c7-4639-b312-b8a0e42f6b5a/shipping-methods/205c72ab-859c-477b-b933-41b7ea0262a7"
          }
        }
      }
    }
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.0,
      "currency" : "EUR",
      "amount" : 0
    } ],
    "_embedded" : {
      "payment-method" : {
        "name" : "PayPal",
        "description" : "Pay with PayPal",
        "officialName" : "PayPal",
        "officialDescription" : "Pay with PayPal",
        "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,
        "activatable" : true,
        "_id" : "676c1b4a-142a-48dd-a29c-6910230c3c2b",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/676c1b4a-142a-48dd-a29c-6910230c3c2b"
          },
          "deactivate-payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/676c1b4a-142a-48dd-a29c-6910230c3c2b/deactivate"
          }
        }
      }
    }
  },
  "billingAddress" : null,
  "shippingAddress" : null,
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 42.0084
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 60.9584
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 60.9584
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 60.9584
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "taxes" : [ {
    "taxClass" : "REGULAR",
    "taxRate" : 0.0,
    "currency" : "EUR",
    "amount" : 0
  } ],
  "taxable" : true,
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "weight" : 2000,
  "checkoutState" : {
    "shippingMethodValid" : true,
    "shippingMethodSelectable" : true,
    "paymentMethodValid" : true,
    "paymentMethodSelectable" : true,
    "billingAddressSet" : false,
    "priceValidToOrder" : true,
    "paymentTransactionStatus" : "NO_APPROVAL_NEEDED",
    "readyToOrder" : false
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/82dbccfe-ce35-450f-845e-d6c487f226fa"
    },
    "line-items" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/82dbccfe-ce35-450f-845e-d6c487f226fa/line-items"
    },
    "shipping-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/82dbccfe-ce35-450f-845e-d6c487f226fa/shipping-methods"
    },
    "shipping-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/82dbccfe-ce35-450f-845e-d6c487f226fa/shipping-methods/default"
    },
    "shipping-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/82dbccfe-ce35-450f-845e-d6c487f226fa/shipping-methods/current"
    },
    "payment-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/82dbccfe-ce35-450f-845e-d6c487f226fa/payment-methods"
    },
    "payment-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/82dbccfe-ce35-450f-845e-d6c487f226fa/payment-methods/default"
    },
    "payment-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/82dbccfe-ce35-450f-845e-d6c487f226fa/payment-methods/current"
    },
    "billing-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/82dbccfe-ce35-450f-845e-d6c487f226fa/billing-address"
    },
    "shipping-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/82dbccfe-ce35-450f-845e-d6c487f226fa/shipping-address"
    }
  },
  "_id" : "82dbccfe-ce35-450f-845e-d6c487f226fa"
}

Delete line item

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

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/9ed41b0a-a154-4075-9bcd-58f55f098ce5/line-items/13025f1f-672c-40f3-96b0-a1e63868ee9f' -i -X DELETE

Example response

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

{
  "lineItems" : [ ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "shipping-method" : {
        "name" : "Standard Shipping 1",
        "description" : "Standard Shipping",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : null,
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 16.95
        },
        "weightBasedPrice" : null,
        "_id" : "2b3021f9-8651-4bb7-858a-ddbb11a56e11",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/522ace58-8f5c-40e9-ade6-4feefb8fbbd3/shipping-methods/2b3021f9-8651-4bb7-858a-ddbb11a56e11"
          }
        }
      }
    }
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "payment-method" : {
        "name" : "PayPal",
        "description" : "Pay with PayPal",
        "officialName" : "PayPal",
        "officialDescription" : "Pay with PayPal",
        "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,
        "activatable" : true,
        "_id" : "a912a78d-d7a9-4485-83b9-81222cd65ddc",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/a912a78d-d7a9-4485-83b9-81222cd65ddc"
          },
          "deactivate-payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/a912a78d-d7a9-4485-83b9-81222cd65ddc/deactivate"
          }
        }
      }
    }
  },
  "billingAddress" : null,
  "shippingAddress" : null,
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 18.95
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 18.95
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 18.95
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "taxes" : [ ],
  "taxable" : true,
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "weight" : 0,
  "checkoutState" : {
    "shippingMethodValid" : true,
    "shippingMethodSelectable" : true,
    "paymentMethodValid" : true,
    "paymentMethodSelectable" : true,
    "billingAddressSet" : false,
    "priceValidToOrder" : true,
    "paymentTransactionStatus" : "NO_APPROVAL_NEEDED",
    "readyToOrder" : false
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9ed41b0a-a154-4075-9bcd-58f55f098ce5"
    },
    "line-items" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9ed41b0a-a154-4075-9bcd-58f55f098ce5/line-items"
    },
    "shipping-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9ed41b0a-a154-4075-9bcd-58f55f098ce5/shipping-methods"
    },
    "shipping-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9ed41b0a-a154-4075-9bcd-58f55f098ce5/shipping-methods/default"
    },
    "shipping-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9ed41b0a-a154-4075-9bcd-58f55f098ce5/shipping-methods/current"
    },
    "payment-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9ed41b0a-a154-4075-9bcd-58f55f098ce5/payment-methods"
    },
    "payment-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9ed41b0a-a154-4075-9bcd-58f55f098ce5/payment-methods/default"
    },
    "payment-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9ed41b0a-a154-4075-9bcd-58f55f098ce5/payment-methods/current"
    },
    "billing-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9ed41b0a-a154-4075-9bcd-58f55f098ce5/billing-address"
    },
    "shipping-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9ed41b0a-a154-4075-9bcd-58f55f098ce5/shipping-address"
    }
  },
  "_id" : "9ed41b0a-a154-4075-9bcd-58f55f098ce5"
}

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.

gender

String

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

title

String

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

firstName

String

The first name of the customer.

middleName

String

The middle name of the customer.

lastName

String

The last name of the customer.

street

String

The street of the customer address.

Must not be empty

houseNumber

String

The house number of the customer address.

street2

String

Additional street field for the customer address.

doorCode

String

The door code of the customer address.

addressExtension

String

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

postalCode

String

The zip code of the customer address.

Must not be empty

city

String

The city of the customer address.

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.

email

String

The email address of the customer.

Must be a well-formed email address. Must not be empty

phone

String

The landline phone number of the customer.

mobile

String

The mobile phone number of the customer.

vatId

String

taxNumber

String

birthDate

String

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/69e834fd-2ebb-427d-9d3f-07aa66d665c3/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":"0815","addressExtension":"","postalCode":"20999","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: 5234

{
  "lineItems" : [ ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "shipping-method" : {
        "name" : "Standard Shipping 1",
        "description" : "Standard Shipping",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : null,
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 16.95
        },
        "weightBasedPrice" : null,
        "_id" : "7a43edbb-4b61-49f4-b6bb-d55cbd8c6aae",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/a2e3b26d-773e-48d7-94ee-439ee75bc88a/shipping-methods/7a43edbb-4b61-49f4-b6bb-d55cbd8c6aae"
          }
        }
      }
    }
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "payment-method" : {
        "name" : "PayPal",
        "description" : "Pay with PayPal",
        "officialName" : "PayPal",
        "officialDescription" : "Pay with PayPal",
        "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,
        "activatable" : true,
        "_id" : "554f63b4-467d-483f-874a-74e1f510d2dd",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/554f63b4-467d-483f-874a-74e1f510d2dd"
          },
          "deactivate-payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/554f63b4-467d-483f-874a-74e1f510d2dd/deactivate"
          }
        }
      }
    }
  },
  "billingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : null,
    "title" : "",
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "Erdgeschoss",
    "addressExtension" : "",
    "postalCode" : "20999",
    "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", "20999 Alsterwasser" ],
    "vatId" : "123456789",
    "taxNumber" : "123-34-6789",
    "birthDate" : "1985-03-20"
  },
  "shippingAddress" : null,
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 18.95
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 18.95
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 18.95
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "taxes" : [ ],
  "taxable" : true,
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "weight" : 0,
  "checkoutState" : {
    "shippingMethodValid" : true,
    "shippingMethodSelectable" : true,
    "paymentMethodValid" : true,
    "paymentMethodSelectable" : true,
    "billingAddressSet" : true,
    "priceValidToOrder" : true,
    "paymentTransactionStatus" : "NO_APPROVAL_NEEDED",
    "readyToOrder" : true
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/69e834fd-2ebb-427d-9d3f-07aa66d665c3"
    },
    "line-items" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/69e834fd-2ebb-427d-9d3f-07aa66d665c3/line-items"
    },
    "shipping-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/69e834fd-2ebb-427d-9d3f-07aa66d665c3/shipping-methods"
    },
    "shipping-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/69e834fd-2ebb-427d-9d3f-07aa66d665c3/shipping-methods/default"
    },
    "shipping-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/69e834fd-2ebb-427d-9d3f-07aa66d665c3/shipping-methods/current"
    },
    "payment-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/69e834fd-2ebb-427d-9d3f-07aa66d665c3/payment-methods"
    },
    "payment-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/69e834fd-2ebb-427d-9d3f-07aa66d665c3/payment-methods/default"
    },
    "payment-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/69e834fd-2ebb-427d-9d3f-07aa66d665c3/payment-methods/current"
    },
    "billing-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/69e834fd-2ebb-427d-9d3f-07aa66d665c3/billing-address"
    },
    "shipping-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/69e834fd-2ebb-427d-9d3f-07aa66d665c3/shipping-address"
    },
    "place-order" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/69e834fd-2ebb-427d-9d3f-07aa66d665c3/order"
    }
  },
  "_id" : "69e834fd-2ebb-427d-9d3f-07aa66d665c3"
}

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.

gender

String

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

title

String

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

firstName

String

The first name of the customer.

middleName

String

The middle name of the customer.

lastName

String

The last name of the customer.

street

String

The street of the customer address.

Must not be empty

houseNumber

String

The house number of the customer address.

street2

String

Additional street field for the customer address.

doorCode

String

The door code of the customer address.

addressExtension

String

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

postalCode

String

The zip code of the customer address.

Must not be empty

city

String

The city of the customer address.

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.

email

String

The email address of the customer.

Must be a well-formed email address. Must not be empty

phone

String

The landline phone number of the customer.

mobile

String

The mobile phone number of the customer.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/dc7802e1-87cf-4301-86ce-5b03a8939fec/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":"0815","addressExtension":"","postalCode":"20999","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: 5049

{
  "lineItems" : [ ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "shipping-method" : {
        "name" : "Standard Shipping 1",
        "description" : "Standard Shipping",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : null,
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 16.95
        },
        "weightBasedPrice" : null,
        "_id" : "ddcb2e58-79c0-421b-8171-eafcceb78215",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/e721bdf5-1aa5-4bc5-9e92-4ff54c674e6e/shipping-methods/ddcb2e58-79c0-421b-8171-eafcceb78215"
          }
        }
      }
    }
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "payment-method" : {
        "name" : "PayPal",
        "description" : "Pay with PayPal",
        "officialName" : "PayPal",
        "officialDescription" : "Pay with PayPal",
        "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,
        "activatable" : true,
        "_id" : "c90df866-55ba-4dd8-a996-26697f06a2eb",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/c90df866-55ba-4dd8-a996-26697f06a2eb"
          },
          "deactivate-payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/c90df866-55ba-4dd8-a996-26697f06a2eb/deactivate"
          }
        }
      }
    }
  },
  "billingAddress" : null,
  "shippingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : null,
    "title" : "",
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "Erdgeschoss",
    "addressExtension" : "",
    "postalCode" : "20999",
    "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", "20999 Alsterwasser" ],
    "doorCode" : "0815"
  },
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 18.95
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 18.95
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 18.95
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "taxes" : [ ],
  "taxable" : true,
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "weight" : 0,
  "checkoutState" : {
    "shippingMethodValid" : true,
    "shippingMethodSelectable" : true,
    "paymentMethodValid" : true,
    "paymentMethodSelectable" : true,
    "billingAddressSet" : false,
    "priceValidToOrder" : true,
    "paymentTransactionStatus" : "NO_APPROVAL_NEEDED",
    "readyToOrder" : false
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/dc7802e1-87cf-4301-86ce-5b03a8939fec"
    },
    "line-items" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/dc7802e1-87cf-4301-86ce-5b03a8939fec/line-items"
    },
    "shipping-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/dc7802e1-87cf-4301-86ce-5b03a8939fec/shipping-methods"
    },
    "shipping-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/dc7802e1-87cf-4301-86ce-5b03a8939fec/shipping-methods/default"
    },
    "shipping-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/dc7802e1-87cf-4301-86ce-5b03a8939fec/shipping-methods/current"
    },
    "payment-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/dc7802e1-87cf-4301-86ce-5b03a8939fec/payment-methods"
    },
    "payment-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/dc7802e1-87cf-4301-86ce-5b03a8939fec/payment-methods/default"
    },
    "payment-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/dc7802e1-87cf-4301-86ce-5b03a8939fec/payment-methods/current"
    },
    "billing-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/dc7802e1-87cf-4301-86ce-5b03a8939fec/billing-address"
    },
    "shipping-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/dc7802e1-87cf-4301-86ce-5b03a8939fec/shipping-address"
    }
  },
  "_id" : "dc7802e1-87cf-4301-86ce-5b03a8939fec"
}

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/d5626611-8fef-4587-91bd-df9a08506c96/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/e4e38808-5b0b-42aa-b14c-4e7769d712aa'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/json;charset=UTF-8
Content-Length: 6170

{
  "lineItems" : [ {
    "_type" : "PRODUCT",
    "_id" : "8c6d875f-d341-4494-9f42-69b2175e8aa2",
    "_ref" : "6ed4c5ff-c596-490d-bf71-814ef233a4a8",
    "name" : "Decorative Sand (2 kg Jumbo Pack)",
    "quantity" : {
      "value" : 1,
      "unit" : "PIECE"
    },
    "singleItemPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 42.0084
    },
    "lineItemPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 42.0084
    },
    "_embedded" : {
      "product" : {
        "_id" : "6ed4c5ff-c596-490d-bf71-814ef233a4a8",
        "sku" : "1018",
        "essentialFeatures" : "Not suitable for children under the age of 8.",
        "_links" : {
          "product" : {
            "href" : "https://api-shop.beyondshop.cloud/api/product-view/products/6ed4c5ff-c596-490d-bf71-814ef233a4a8?locale=de-DE"
          },
          "default-image-data" : {
            "href" : "https://api-shop.beyondshop.cloud/api/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
            "templated" : true
          }
        }
      }
    },
    "quantityInt" : 1,
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 7.981596
    },
    "_links" : {
      "self" : {
        "href" : "https://api-shop.beyondshop.cloud/api/carts/d5626611-8fef-4587-91bd-df9a08506c96/line-items/8c6d875f-d341-4494-9f42-69b2175e8aa2"
      }
    }
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.0,
      "currency" : "EUR",
      "amount" : 0
    } ],
    "_embedded" : {
      "shipping-method" : {
        "name" : "Standard Shipping 1",
        "description" : "Standard Shipping",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : null,
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 16.95
        },
        "weightBasedPrice" : null,
        "_id" : "ec7681b8-87b3-4cea-8e0e-eb7b1f7a3d0f",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/0664156f-a42a-4f3d-91b8-0d7ade6310ac/shipping-methods/ec7681b8-87b3-4cea-8e0e-eb7b1f7a3d0f"
          }
        }
      }
    }
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 1.179168
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.0,
      "currency" : "EUR",
      "amount" : 0
    } ],
    "_embedded" : {
      "payment-method" : {
        "name" : "Credit Card",
        "description" : "Pay with CreditCard",
        "officialName" : "Credit Card",
        "officialDescription" : "Pay with CreditCard",
        "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,
        "activatable" : true,
        "_id" : "e4e38808-5b0b-42aa-b14c-4e7769d712aa",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/e4e38808-5b0b-42aa-b14c-4e7769d712aa"
          },
          "deactivate-payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/e4e38808-5b0b-42aa-b14c-4e7769d712aa/deactivate"
          }
        }
      }
    }
  },
  "billingAddress" : null,
  "shippingAddress" : null,
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 42.0084
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 60.137568
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 60.137568
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 60.137568
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "taxes" : [ {
    "taxClass" : "REGULAR",
    "taxRate" : 0.0,
    "currency" : "EUR",
    "amount" : 0
  } ],
  "taxable" : true,
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "weight" : 2000,
  "checkoutState" : {
    "shippingMethodValid" : true,
    "shippingMethodSelectable" : true,
    "paymentMethodValid" : true,
    "paymentMethodSelectable" : true,
    "billingAddressSet" : false,
    "priceValidToOrder" : true,
    "paymentTransactionStatus" : "NO_APPROVAL_NEEDED",
    "readyToOrder" : false
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/d5626611-8fef-4587-91bd-df9a08506c96"
    },
    "line-items" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/d5626611-8fef-4587-91bd-df9a08506c96/line-items"
    },
    "shipping-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/d5626611-8fef-4587-91bd-df9a08506c96/shipping-methods"
    },
    "shipping-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/d5626611-8fef-4587-91bd-df9a08506c96/shipping-methods/default"
    },
    "shipping-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/d5626611-8fef-4587-91bd-df9a08506c96/shipping-methods/current"
    },
    "payment-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/d5626611-8fef-4587-91bd-df9a08506c96/payment-methods"
    },
    "payment-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/d5626611-8fef-4587-91bd-df9a08506c96/payment-methods/default"
    },
    "payment-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/d5626611-8fef-4587-91bd-df9a08506c96/payment-methods/current"
    },
    "billing-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/d5626611-8fef-4587-91bd-df9a08506c96/billing-address"
    },
    "shipping-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/d5626611-8fef-4587-91bd-df9a08506c96/shipping-address"
    }
  },
  "_id" : "d5626611-8fef-4587-91bd-df9a08506c96"
}

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/9d174fe9-d3e2-4458-9f92-b4806678fa8c/payment-methods/default' -i -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/json;charset=UTF-8
Content-Length: 4410

{
  "lineItems" : [ ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "shipping-method" : {
        "name" : "Standard Shipping 1",
        "description" : "Standard Shipping",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : null,
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 16.95
        },
        "weightBasedPrice" : null,
        "_id" : "4775ad91-fac1-48c9-a1ee-732e8b6183f4",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/3df0d44a-ba3f-4cc4-befc-584fe363a97b/shipping-methods/4775ad91-fac1-48c9-a1ee-732e8b6183f4"
          }
        }
      }
    }
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "payment-method" : {
        "name" : "PayPal",
        "description" : "Pay with PayPal",
        "officialName" : "PayPal",
        "officialDescription" : "Pay with PayPal",
        "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,
        "activatable" : true,
        "_id" : "8aec3930-3a23-4003-963d-a3fed6cb9d2c",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/8aec3930-3a23-4003-963d-a3fed6cb9d2c"
          },
          "deactivate-payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/8aec3930-3a23-4003-963d-a3fed6cb9d2c/deactivate"
          }
        }
      }
    }
  },
  "billingAddress" : null,
  "shippingAddress" : null,
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 18.95
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 18.95
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 18.95
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "taxes" : [ ],
  "taxable" : true,
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "weight" : 0,
  "checkoutState" : {
    "shippingMethodValid" : true,
    "shippingMethodSelectable" : true,
    "paymentMethodValid" : true,
    "paymentMethodSelectable" : true,
    "billingAddressSet" : false,
    "priceValidToOrder" : true,
    "paymentTransactionStatus" : "NO_APPROVAL_NEEDED",
    "readyToOrder" : false
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9d174fe9-d3e2-4458-9f92-b4806678fa8c"
    },
    "line-items" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9d174fe9-d3e2-4458-9f92-b4806678fa8c/line-items"
    },
    "shipping-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9d174fe9-d3e2-4458-9f92-b4806678fa8c/shipping-methods"
    },
    "shipping-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9d174fe9-d3e2-4458-9f92-b4806678fa8c/shipping-methods/default"
    },
    "shipping-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9d174fe9-d3e2-4458-9f92-b4806678fa8c/shipping-methods/current"
    },
    "payment-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9d174fe9-d3e2-4458-9f92-b4806678fa8c/payment-methods"
    },
    "payment-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9d174fe9-d3e2-4458-9f92-b4806678fa8c/payment-methods/default"
    },
    "payment-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9d174fe9-d3e2-4458-9f92-b4806678fa8c/payment-methods/current"
    },
    "billing-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9d174fe9-d3e2-4458-9f92-b4806678fa8c/billing-address"
    },
    "shipping-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/9d174fe9-d3e2-4458-9f92-b4806678fa8c/shipping-address"
    }
  },
  "_id" : "9d174fe9-d3e2-4458-9f92-b4806678fa8c"
}

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/28a2d1a3-b5d3-4d79-bfed-8eb67267b59c/payment-methods/current' -i -H 'Content-Type: application/json' -H 'Accept: application/hal+json'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 864

{
  "name" : "PayPal",
  "description" : "Pay with PayPal",
  "officialName" : "PayPal",
  "officialDescription" : "Pay with PayPal",
  "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,
  "activatable" : true,
  "_id" : "1388f10e-8f0c-467b-8118-eb6ecb0cd97f",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/1388f10e-8f0c-467b-8118-eb6ecb0cd97f"
    },
    "deactivate-payment-method" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/1388f10e-8f0c-467b-8118-eb6ecb0cd97f/deactivate"
    }
  }
}

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/0d29b072-adb3-452e-9441-d73058fad88c/payment-methods' -i -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 administration 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 mininmum 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.activatable

Boolean

Indicates if a payment method can be activated (feature enabled for the shop). 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).

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1514

{
  "_embedded" : {
    "payment-methods" : [ {
      "lineItemPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 2
      },
      "selectable" : true,
      "_embedded" : {
        "payment-method" : {
          "name" : "PayPal",
          "description" : "Pay with PayPal",
          "officialName" : "PayPal",
          "officialDescription" : "Pay with PayPal",
          "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,
          "activatable" : true,
          "_id" : "ad3cc92e-16aa-47b8-a686-36ccdbb6b6b4",
          "_links" : {
            "self" : {
              "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/ad3cc92e-16aa-47b8-a686-36ccdbb6b6b4"
            },
            "deactivate-payment-method" : {
              "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/ad3cc92e-16aa-47b8-a686-36ccdbb6b6b4/deactivate"
            }
          }
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/0d29b072-adb3-452e-9441-d73058fad88c/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 redirect URI if the payment authorization was not successful.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/516d6869-b4b0-432d-b943-eb399f99b501/create-payment' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -d '{
  "returnUri" : "http://some.com/return",
  "cancelUri" : "http://some.com/cancel"
}'

Response body properties

Path Type Description

approvalUri

String

The URI used to approve the payment. The client has to redirect to this URI to initiate the approval.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 47

{
  "approvalUri" : "http://some.de/approval"
}

Set current cart shipping method

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

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/698a5282-482f-49d4-a7fd-ac277e452c33/shipping-methods/current' -i -X PUT -H 'Content-Type: text/uri-list' -H 'Accept: application/json' -d 'https://api-shop.beyondshop.cloud/api/shipping-zones/704f4aec-a99d-4ccd-aa33-234cedcd2a84/shipping-methods/deaca413-e21d-4134-a96c-32f021843bae'

Example response

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

{
  "lineItems" : [ ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 50
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "shipping-method" : {
        "name" : "Express",
        "description" : "Shipping overnight, delivery on the next day.",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : {
          "currency" : "EUR",
          "amount" : 1000
        },
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 50
        },
        "weightBasedPrice" : null,
        "_id" : "deaca413-e21d-4134-a96c-32f021843bae",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/704f4aec-a99d-4ccd-aa33-234cedcd2a84/shipping-methods/deaca413-e21d-4134-a96c-32f021843bae"
          }
        }
      }
    }
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "payment-method" : {
        "name" : "PayPal",
        "description" : "Pay with PayPal",
        "officialName" : "PayPal",
        "officialDescription" : "Pay with PayPal",
        "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,
        "activatable" : true,
        "_id" : "e73606e3-6edf-41d8-b5c9-536cb25b6528",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/e73606e3-6edf-41d8-b5c9-536cb25b6528"
          },
          "deactivate-payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/e73606e3-6edf-41d8-b5c9-536cb25b6528/deactivate"
          }
        }
      }
    }
  },
  "billingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : null,
    "title" : "",
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "Erdgeschoss",
    "addressExtension" : "",
    "postalCode" : "20999",
    "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", "20999 Alsterwasser" ],
    "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" : "",
    "postalCode" : "20999",
    "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", "20999 Alsterwasser" ],
    "doorCode" : "0815"
  },
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 52
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 52
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 52
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "taxes" : [ ],
  "taxable" : true,
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "weight" : 0,
  "checkoutState" : {
    "shippingMethodValid" : true,
    "shippingMethodSelectable" : true,
    "paymentMethodValid" : true,
    "paymentMethodSelectable" : true,
    "billingAddressSet" : true,
    "priceValidToOrder" : true,
    "paymentTransactionStatus" : "NO_APPROVAL_NEEDED",
    "readyToOrder" : true
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/698a5282-482f-49d4-a7fd-ac277e452c33"
    },
    "line-items" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/698a5282-482f-49d4-a7fd-ac277e452c33/line-items"
    },
    "shipping-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/698a5282-482f-49d4-a7fd-ac277e452c33/shipping-methods"
    },
    "shipping-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/698a5282-482f-49d4-a7fd-ac277e452c33/shipping-methods/default"
    },
    "shipping-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/698a5282-482f-49d4-a7fd-ac277e452c33/shipping-methods/current"
    },
    "payment-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/698a5282-482f-49d4-a7fd-ac277e452c33/payment-methods"
    },
    "payment-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/698a5282-482f-49d4-a7fd-ac277e452c33/payment-methods/default"
    },
    "payment-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/698a5282-482f-49d4-a7fd-ac277e452c33/payment-methods/current"
    },
    "billing-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/698a5282-482f-49d4-a7fd-ac277e452c33/billing-address"
    },
    "shipping-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/698a5282-482f-49d4-a7fd-ac277e452c33/shipping-address"
    },
    "place-order" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/698a5282-482f-49d4-a7fd-ac277e452c33/order"
    }
  },
  "_id" : "698a5282-482f-49d4-a7fd-ac277e452c33"
}

Set cart shipping method to current default

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

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/40c25760-460b-4ec4-92d0-233936e59702/shipping-methods/default' -i -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/json;charset=UTF-8
Content-Length: 4410

{
  "lineItems" : [ ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "shipping-method" : {
        "name" : "Standard Shipping 1",
        "description" : "Standard Shipping",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : null,
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 16.95
        },
        "weightBasedPrice" : null,
        "_id" : "96126053-6f80-40f3-a48b-084f6990e1bd",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/82786d41-ec76-46b1-b150-112028715402/shipping-methods/96126053-6f80-40f3-a48b-084f6990e1bd"
          }
        }
      }
    }
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2
    },
    "lineItemTaxes" : [ ],
    "_embedded" : {
      "payment-method" : {
        "name" : "PayPal",
        "description" : "Pay with PayPal",
        "officialName" : "PayPal",
        "officialDescription" : "Pay with PayPal",
        "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,
        "activatable" : true,
        "_id" : "34e284fb-844e-48b2-8c7d-1748a65a904f",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/34e284fb-844e-48b2-8c7d-1748a65a904f"
          },
          "deactivate-payment-method" : {
            "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/34e284fb-844e-48b2-8c7d-1748a65a904f/deactivate"
          }
        }
      }
    }
  },
  "billingAddress" : null,
  "shippingAddress" : null,
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 18.95
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 18.95
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 18.95
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "taxes" : [ ],
  "taxable" : true,
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "weight" : 0,
  "checkoutState" : {
    "shippingMethodValid" : true,
    "shippingMethodSelectable" : true,
    "paymentMethodValid" : true,
    "paymentMethodSelectable" : true,
    "billingAddressSet" : false,
    "priceValidToOrder" : true,
    "paymentTransactionStatus" : "NO_APPROVAL_NEEDED",
    "readyToOrder" : false
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/40c25760-460b-4ec4-92d0-233936e59702"
    },
    "line-items" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/40c25760-460b-4ec4-92d0-233936e59702/line-items"
    },
    "shipping-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/40c25760-460b-4ec4-92d0-233936e59702/shipping-methods"
    },
    "shipping-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/40c25760-460b-4ec4-92d0-233936e59702/shipping-methods/default"
    },
    "shipping-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/40c25760-460b-4ec4-92d0-233936e59702/shipping-methods/current"
    },
    "payment-method-available" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/40c25760-460b-4ec4-92d0-233936e59702/payment-methods"
    },
    "payment-method-default" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/40c25760-460b-4ec4-92d0-233936e59702/payment-methods/default"
    },
    "payment-method-current" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/40c25760-460b-4ec4-92d0-233936e59702/payment-methods/current"
    },
    "billing-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/40c25760-460b-4ec4-92d0-233936e59702/billing-address"
    },
    "shipping-address" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/40c25760-460b-4ec4-92d0-233936e59702/shipping-address"
    }
  },
  "_id" : "40c25760-460b-4ec4-92d0-233936e59702"
}

Show current cart shipping method details

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

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/2b80390c-70e9-4b0a-bba7-c5e08a5970ad/shipping-methods/current' -i -H 'Content-Type: application/json' -H 'Accept: application/hal+json'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 512

{
  "name" : "Standard Shipping 1",
  "description" : "Standard Shipping",
  "taxClass" : "REGULAR",
  "position" : 0,
  "freeShippingValue" : null,
  "fixedPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 16.95
  },
  "weightBasedPrice" : null,
  "_id" : "b8b78271-9d0f-4de6-9b55-7f3c9260fed4",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/61d060fd-8fa3-4e7a-a818-a15b7efc5cd5/shipping-methods/b8b78271-9d0f-4de6-9b55-7f3c9260fed4"
    }
  }
}

Show applicable cart shipping method details

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

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

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/carts/b97ae708-f84b-4791-bbc7-f22d197a11c1/shipping-methods' -i -H 'Content-Type: application/json' -H 'Accept: application/hal+json'

Response body properties

Path Type Description

_embedded.shipping-methods[].selectable

Boolean

Indicates if the shipping method can be selected for the current cart. A shipping method can be become non-selectable if the cart is modified, so that the maximum weight for weight based price is exceeded. A cart with a non-selectable shipping method cannot be ordered.

_embedded.shipping-methods[].lineItemPrice

Object

The calculated price for this shipping method on the current cart.

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

String

The immutable, unique identifier of the requested resource.

_embedded.shipping-methods[]._embedded.shipping-method.weightBasedPrice

Null

The price depending on the package weight.

_embedded.shipping-methods[]._embedded.shipping-method.fixedPrice

Object

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

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

Number

The sorting position of the shipping method in the merchant administration in relation to other shipping methods.

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

String

The name of the shipping method.

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

String

description

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

String

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

_embedded.shipping-methods[]._embedded.shipping-method.freeShippingValue

Null

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

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1065

{
  "_embedded" : {
    "shipping-methods" : [ {
      "lineItemPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 16.95
      },
      "selectable" : true,
      "_embedded" : {
        "shipping-method" : {
          "name" : "Standard Shipping 1",
          "description" : "Standard Shipping",
          "taxClass" : "REGULAR",
          "position" : 0,
          "freeShippingValue" : null,
          "fixedPrice" : {
            "taxModel" : "GROSS",
            "currency" : "EUR",
            "amount" : 16.95
          },
          "weightBasedPrice" : null,
          "_id" : "03c0b2a2-bdb9-4769-8c27-c1322295d480",
          "_links" : {
            "self" : {
              "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/cd9df43e-c28c-4696-8c48-d6a5c35785a4/shipping-methods/03c0b2a2-bdb9-4769-8c27-c1322295d480"
            }
          }
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/carts/b97ae708-f84b-4791-bbc7-f22d197a11c1/shipping-methods"
    }
  }
}

Categories

The categories resource is used to manage categories of a shop.

List categories

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

Required scopes

catg:r

Example request

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

Response body properties

Path Type Description

_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.

_links

Object

See Hypermedia

page

Object

See Pagination

Links

Relation Description

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1435

{
  "_embedded" : {
    "categories" : [ {
      "name" : "manual category",
      "label" : "manual-category",
      "type" : "MANUAL",
      "query" : {"bool":{"filter":[{"terms":{"id":["6c449297-65fc-41aa-a49c-68a3561b33e5","6c449297-65fc-41aa-a49c-68a3561b33e6"]}}]}},
      "_id" : "3602ae6b-5731-41a2-8056-39f1ef3f19e8",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/categories/3602ae6b-5731-41a2-8056-39f1ef3f19e8"
        },
        "category" : {
          "href" : "https://api-shop.beyondshop.cloud/api/categories/3602ae6b-5731-41a2-8056-39f1ef3f19e8"
        }
      }
    }, {
      "name" : "smart category",
      "label" : "smart-category",
      "type" : "SMART",
      "query" : {"bool":{"filter":[{"term":{"tags":"Men"}}]}},
      "_id" : "c573a71e-a3f7-4a3f-8106-257e28e62fa6",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/categories/c573a71e-a3f7-4a3f-8106-257e28e62fa6"
        },
        "category" : {
          "href" : "https://api-shop.beyondshop.cloud/api/categories/c573a71e-a3f7-4a3f-8106-257e28e62fa6"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories{?page,size,sort}",
      "templated" : true
    },
    "profile" : {
      "href" : "https://api-shop.beyondshop.cloud/api/profile/categories"
    }
  },
  "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.

Must not be empty

label

String

The label of the product collection.

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":"MyCategory","label":"my-label","type":"SMART","query":{"bool":{"filter":[{"term":{"tags":"Men"}}]}}}'

Example response

HTTP/1.1 201 Created
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Location: https://api-shop.beyondshop.cloud/api/categories/47d5540f-65b5-41c8-be2a-86385f41c4fd
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 180

{
  "name" : "MyCategory",
  "label" : "my-label",
  "type" : "SMART",
  "query" : {"bool":{"filter":[{"term":{"tags":"Men"}}]}},
  "_id" : "47d5540f-65b5-41c8-be2a-86385f41c4fd"
}

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/022214db-a511-4810-978d-37b19f0a7f32' -i -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 category. Current representation of the resource. See Hypermedia.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Last-Modified: Fri, 09 Feb 2018 14:25:04 GMT
ETag: "1"
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 437

{
  "name" : "smart category",
  "label" : "smart-category",
  "type" : "SMART",
  "query" : {"bool":{"filter":[{"term":{"tags":"Men"}}]}},
  "_id" : "022214db-a511-4810-978d-37b19f0a7f32",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/022214db-a511-4810-978d-37b19f0a7f32"
    },
    "category" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/022214db-a511-4810-978d-37b19f0a7f32"
    }
  }
}

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.

Must not be empty

label

String

The label of the product collection.

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/3306ec83-a65b-480c-9b05-d1611e217a57' -i -X PUT -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>' -d '{"name":"updated name","label":"updated-name","type":"MANUAL","query":{"bool":{"filter":[{"terms":{"id":["6c449297-65fc-41aa-a49c-68a3561b33e5","6c449297-65fc-41aa-a49c-68a3561b33e6"]}}]}}}'

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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 509

{
  "name" : "updated name",
  "label" : "smart-category",
  "type" : "MANUAL",
  "query" : {"bool":{"filter":[{"terms":{"id":["6c449297-65fc-41aa-a49c-68a3561b33e5","6c449297-65fc-41aa-a49c-68a3561b33e6"]}}]}},
  "_id" : "3306ec83-a65b-480c-9b05-d1611e217a57",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/3306ec83-a65b-480c-9b05-d1611e217a57"
    },
    "category" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/3306ec83-a65b-480c-9b05-d1611e217a57"
    }
  }
}

Update category partially (json patch)

A PATCH request is issued 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/0bc0d8f0-334b-47e1-bc7a-2d2b012f3320' -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":"smart category"},{"op":"replace","path":"/name","value":"patched name"},{"op":"replace","path":"/type","value":"MANUAL"},{"op":"replace","path":"/query","value":{"bool":{"filter":[{"terms":{"id":["6c449297-65fc-41aa-a49c-68a3561b33e5","6c449297-65fc-41aa-a49c-68a3561b33e6"]}}]}}}]'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
ETag: "2"
Last-Modified: Fri, 09 Feb 2018 14:25:17 GMT
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 509

{
  "name" : "patched name",
  "label" : "smart-category",
  "type" : "MANUAL",
  "query" : {"bool":{"filter":[{"terms":{"id":["6c449297-65fc-41aa-a49c-68a3561b33e5","6c449297-65fc-41aa-a49c-68a3561b33e6"]}}]}},
  "_id" : "0bc0d8f0-334b-47e1-bc7a-2d2b012f3320",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/0bc0d8f0-334b-47e1-bc7a-2d2b012f3320"
    },
    "category" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/0bc0d8f0-334b-47e1-bc7a-2d2b012f3320"
    }
  }
}

Update category partially (json)

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

Required scopes

catg:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/categories/ac221540-d714-4227-ae16-bf6349cd5a53' -i -X PATCH -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>' -d '{"name":"patched name","type":"MANUAL","query":{"bool":{"filter":[{"terms":{"id":["6c449297-65fc-41aa-a49c-68a3561b33e5","6c449297-65fc-41aa-a49c-68a3561b33e6"]}}]}}}'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
ETag: "2"
Last-Modified: Fri, 09 Feb 2018 14:25:20 GMT
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 509

{
  "name" : "patched name",
  "label" : "smart-category",
  "type" : "MANUAL",
  "query" : {"bool":{"filter":[{"terms":{"id":["6c449297-65fc-41aa-a49c-68a3561b33e5","6c449297-65fc-41aa-a49c-68a3561b33e6"]}}]}},
  "_id" : "ac221540-d714-4227-ae16-bf6349cd5a53",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/ac221540-d714-4227-ae16-bf6349cd5a53"
    },
    "category" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/ac221540-d714-4227-ae16-bf6349cd5a53"
    }
  }
}

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/14d694a0-2ef4-4e35-b7ad-a433c6e15c70' -i -X DELETE -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

List category meta-information

The categories resource offers API meta-information if you follow the profile link.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/profile/categories' -i

Example response

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

{
  "alps" : {
    "version" : "1.0",
    "descriptors" : [ {
      "id" : "category-representation",
      "href" : "https://api-shop.beyondshop.cloud/api/profile/categories",
      "descriptors" : [ {
        "name" : "name",
        "type" : "SEMANTIC"
      }, {
        "name" : "label",
        "type" : "SEMANTIC"
      }, {
        "name" : "type",
        "doc" : {
          "value" : "SMART, MANUAL",
          "format" : "TEXT"
        },
        "type" : "SEMANTIC"
      }, {
        "name" : "_id",
        "type" : "SEMANTIC"
      } ]
    }, {
      "id" : "create-categories",
      "name" : "categories",
      "type" : "UNSAFE",
      "rt" : "#category-representation"
    }, {
      "id" : "get-categories",
      "name" : "categories",
      "type" : "SAFE",
      "rt" : "#category-representation",
      "descriptors" : [ {
        "name" : "page",
        "doc" : {
          "value" : "The page to return.",
          "format" : "TEXT"
        },
        "type" : "SEMANTIC"
      }, {
        "name" : "size",
        "doc" : {
          "value" : "The size of the page to return.",
          "format" : "TEXT"
        },
        "type" : "SEMANTIC"
      }, {
        "name" : "sort",
        "doc" : {
          "value" : "The sorting criteria to use to calculate the content of the page.",
          "format" : "TEXT"
        },
        "type" : "SEMANTIC"
      } ]
    }, {
      "id" : "delete-category",
      "name" : "category",
      "type" : "IDEMPOTENT",
      "rt" : "#category-representation"
    }, {
      "id" : "get-category",
      "name" : "category",
      "type" : "SAFE",
      "rt" : "#category-representation"
    }, {
      "id" : "update-category",
      "name" : "category",
      "type" : "IDEMPOTENT",
      "rt" : "#category-representation"
    }, {
      "id" : "patch-category",
      "name" : "category",
      "type" : "UNSAFE",
      "rt" : "#category-representation"
    } ]
  }
}

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/categories/022214db-a511-4810-978d-37b19f0a7f32' -i -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 category. Current representation of the resource. See Hypermedia.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Last-Modified: Fri, 09 Feb 2018 14:25:04 GMT
ETag: "1"
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 437

{
  "name" : "smart category",
  "label" : "smart-category",
  "type" : "SMART",
  "query" : {"bool":{"filter":[{"term":{"tags":"Men"}}]}},
  "_id" : "022214db-a511-4810-978d-37b19f0a7f32",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/022214db-a511-4810-978d-37b19f0a7f32"
    },
    "category" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/022214db-a511-4810-978d-37b19f0a7f32"
    }
  }
}

Show enhanced view of product category details

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

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/categories/652c7baf-bcab-45b5-a182-25eebd80dba6?projection=enhancedCategoryProjection' -i -H 'Content-Type: application/json' -H 'Accept: application/hal+json'

Response body properties

Path Type Description

_id

String

The unique identifier of the category.

_indexedAt

String

The time of storing this document in the search index.

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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 578

{
  "_id" : "652c7baf-bcab-45b5-a182-25eebd80dba6",
  "_indexedAt" : "2018-02-12T12:26:46.815",
  "type" : "SMART",
  "name" : "Category A",
  "label" : "category-a",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/652c7baf-bcab-45b5-a182-25eebd80dba6"
    },
    "category" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/652c7baf-bcab-45b5-a182-25eebd80dba6{?projection}",
      "templated" : true
    },
    "products" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/652c7baf-bcab-45b5-a182-25eebd80dba6/products"
    }
  }
}

List product categories

A GET request is used to list all product categories.

Example request

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

Response body properties

Path Type Description

_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.

_links

Object

See Hypermedia

page

Object

See Pagination

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1435

{
  "_embedded" : {
    "categories" : [ {
      "name" : "manual category",
      "label" : "manual-category",
      "type" : "MANUAL",
      "query" : {"bool":{"filter":[{"terms":{"id":["6c449297-65fc-41aa-a49c-68a3561b33e5","6c449297-65fc-41aa-a49c-68a3561b33e6"]}}]}},
      "_id" : "3602ae6b-5731-41a2-8056-39f1ef3f19e8",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/categories/3602ae6b-5731-41a2-8056-39f1ef3f19e8"
        },
        "category" : {
          "href" : "https://api-shop.beyondshop.cloud/api/categories/3602ae6b-5731-41a2-8056-39f1ef3f19e8"
        }
      }
    }, {
      "name" : "smart category",
      "label" : "smart-category",
      "type" : "SMART",
      "query" : {"bool":{"filter":[{"term":{"tags":"Men"}}]}},
      "_id" : "c573a71e-a3f7-4a3f-8106-257e28e62fa6",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/categories/c573a71e-a3f7-4a3f-8106-257e28e62fa6"
        },
        "category" : {
          "href" : "https://api-shop.beyondshop.cloud/api/categories/c573a71e-a3f7-4a3f-8106-257e28e62fa6"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories{?page,size,sort}",
      "templated" : true
    },
    "profile" : {
      "href" : "https://api-shop.beyondshop.cloud/api/profile/categories"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

List products

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

For the response body properties see category list structure.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/categories/512e2a9b-faaa-4135-850f-9507d659dc39/products' -i -H 'Content-Type: application/hal+json' -H 'Accept: application/hal+json'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1503

{
  "_embedded" : {
    "products" : [ {
      "_id" : "616d5aeb-49f2-4288-8a0a-760e42392e7c",
      "sku" : "b2210e9d-1d75-417e-a581-afffd21def8f",
      "name" : "Funky Trousers",
      "salesPrice" : {
        "amount" : 1.0,
        "currency" : "EUR"
      },
      "listPrice" : null,
      "onSale" : false,
      "listPriceText" : null,
      "shippingDimension" : {
        "length" : 16,
        "width" : 17,
        "height" : 18
      },
      "refPrice" : {
        "refQuantity" : 100,
        "unit" : "GRAM",
        "quantity" : 200,
        "price" : {
          "amount" : 12.0,
          "currency" : "EUR"
        }
      },
      "availabilityState" : "IN_STOCK",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/Cardigan.jpg?hash=e9a1ce5c0c6abfebec8fb1f6faf77dca7e6e7777{&width,height,upscale}",
          "templated" : true
        },
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/616d5aeb-49f2-4288-8a0a-760e42392e7c"
        },
        "product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/616d5aeb-49f2-4288-8a0a-760e42392e7c{?projection}",
          "templated" : true
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/512e2a9b-faaa-4135-850f-9507d659dc39/products?page=0&size=40&sort=id,asc"
    }
  },
  "page" : {
    "size" : 40,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

List product categories assigned to product

A GET request is used to list all product categories a product is part of.

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/categories/search/find-by-product?productId=be542492-97d3-429c-b173-ddbc3536ad3c' -i -H 'Content-Type: application/json' -H 'Accept: application/hal+json'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1531

{
  "_embedded" : {
    "categories" : [ {
      "type" : "SMART",
      "name" : "category that loves everyone",
      "label" : null,
      "_id" : "e3353004-61ad-4a07-b715-98672fe725ca",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/categories/e3353004-61ad-4a07-b715-98672fe725ca"
        },
        "category" : {
          "href" : "https://api-shop.beyondshop.cloud/api/categories/e3353004-61ad-4a07-b715-98672fe725ca{?projection}",
          "templated" : true
        },
        "products" : {
          "href" : "https://api-shop.beyondshop.cloud/api/categories/e3353004-61ad-4a07-b715-98672fe725ca/products"
        }
      }
    }, {
      "type" : "MANUAL",
      "name" : "category that matches product 1 in a complicated way",
      "label" : null,
      "_id" : "f28ff712-ece9-4d24-8a08-d155fb2ab503",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/categories/f28ff712-ece9-4d24-8a08-d155fb2ab503"
        },
        "category" : {
          "href" : "https://api-shop.beyondshop.cloud/api/categories/f28ff712-ece9-4d24-8a08-d155fb2ab503{?projection}",
          "templated" : true
        },
        "products" : {
          "href" : "https://api-shop.beyondshop.cloud/api/categories/f28ff712-ece9-4d24-8a08-d155fb2ab503/products"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/search/find-by-product?page=0&size=40"
    }
  },
  "page" : {
    "size" : 40,
    "totalElements" : 2,
    "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/categories/search/find-by-label?label=category-a' -i -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

Links

Relation Description

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 534

{
  "type" : "SMART",
  "name" : "Category A",
  "label" : "category-a",
  "_id" : "94a89e08-48fb-4a8d-93f7-e71ab2c39425",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/94a89e08-48fb-4a8d-93f7-e71ab2c39425"
    },
    "category" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/94a89e08-48fb-4a8d-93f7-e71ab2c39425{?projection}",
      "templated" : true
    },
    "products" : {
      "href" : "https://api-shop.beyondshop.cloud/api/categories/94a89e08-48fb-4a8d-93f7-e71ab2c39425/products"
    }
  }
}

Google Shopping

Access Data

Create access data

The access data is required by the service to authenticate against Google Shopping.

Use a POST request to create access data.

Required scopes

gsad:c

Request body properties

Path Type Description Constraints

merchantId

String

The unique identifier for the Google account that the merchant uses for Google Shopping.

redirectUri

String

The URI to which the merchant will be redirected after the confirmation of the Google API access consent dialog.

Not a valid URI

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/access-data' -i -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer <Access token>' -d '{
  "merchantId" : "1168736784",
  "redirectUri" : "http://2020.beyondshop.cloud/merchant-ui"
}'

Example response

HTTP/1.1 201 Created
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Location: https://api-shop.beyondshop.cloud/api/access-data/821a6e8e-4742-4422-a36d-33014771727d
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 425

{
  "authorizeUrl" : "https://google-auth.com/o/oauth2/auth?access_type=offline&client_id=32649939298-sh91tfd793vkuudkk34aliqeg8astose.apps.googleusercontent.com&redirect_uri=http://system.epages.works/api/google-shopping/nonce&response_type=code&scope=https://www.googleapis.com/auth/content+https://www.googleapis.com/auth/siteverification&state=66f52994-bcae-40ee-bd8b-f37d00367bcc",
  "nonceExpirationDate" : 1518790330
}

Show access data details

Use a GET request to retrieve the access data details.

Required scopes

gsad:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/access-data' -i -H 'Content-Type: application/json' -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

merchantId

String

The unique identifier for the Google account that the merchant uses for Google Shopping.

tokenExpirationDate

Number

The expiration date of the access token. Displayed in seconds since the start of the Epoch. Refer to RFC 7519.

hasRefreshToken

Boolean

Indicates if a refresh token for the Google API is stored. Can be true or false.

hasAccessToken

Boolean

Indicates if an access token for the Google API is stored. Can be true or false.

_id

String

The immutable, unique identifier of the requested resource.

_links

Object

See Hypermedia

Links

Relation Description

access-data

The access data to authenticate with the Google Shopping API.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 433

{
  "merchantId" : "merchantId",
  "tokenExpirationDate" : 123456789,
  "_id" : "d0dc1915-a1c3-41ca-9dbc-09bd4ebca579",
  "hasAccessToken" : true,
  "hasRefreshToken" : true,
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/access-data/d0dc1915-a1c3-41ca-9dbc-09bd4ebca579"
    },
    "access-data" : {
      "href" : "https://api-shop.beyondshop.cloud/api/access-data{?page,size,sort}",
      "templated" : true
    }
  }
}

Update access data

Use a PUT request to update the access data.

Required scopes

gsad:u

Request body properties

Path Type Description Constraints

merchantId

String

The unique identifier for the Google account that the merchant uses for Google Shopping.

Must not be null

accessToken

String

The encoded access token retrieved from the Google Authorization Server to access the Google API.

refreshToken

String

The refresh token retrieved from the Google Authorization Server to obtain a renewed access token.

tokenExpirationDate

Number

The expiration date of the access token. Displayed in seconds since the start of the Epoch. Refer to RFC 7519.

Must be at least 0 and at most 9223372036854775807

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/access-data' -i -X PUT -H 'Content-Type: application/json' -H 'Authorization: Bearer <Access token>' -d '{
  "merchantId" : "123456789",
  "refreshToken" : "your refresh token",
  "accessToken" : "my new access token",
  "tokenExpirationDate" : 123456789
}'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 432

{
  "merchantId" : "123456789",
  "tokenExpirationDate" : 123456789,
  "_id" : "3f23b821-ea76-4ecb-ad01-b64890398cd6",
  "hasAccessToken" : true,
  "hasRefreshToken" : true,
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/access-data/3f23b821-ea76-4ecb-ad01-b64890398cd6"
    },
    "access-data" : {
      "href" : "https://api-shop.beyondshop.cloud/api/access-data{?page,size,sort}",
      "templated" : true
    }
  }
}

Delete access data

Use a DELETE request to delete the access data.

Required scopes

gsad:d

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/access-data' -i -X DELETE -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

Products

Add a product to Google Shopping

In order to add a product to Google Shopping, first a Google Shopping product has to be created. Only then, a product can be published on Google Shopping, see Publish individual Google Shopping product or Publish a list of Google Shopping products.

Use a POST request to add a product to Google Shopping.

Required scopes

gspr:c

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products' -i -X POST -H 'Content-Type: text/uri-list' -H 'Authorization: Bearer <Access token>' -d 'https://api-shop.beyondshop.cloud/api/api/products/720999b3-1a0a-47e4-9cfe-e157d1ccd98e
https://api-shop.beyondshop.cloud/api/api/products/58aef62d-1acc-4baf-b206-c5aa2cc7107d
https://api-shop.beyondshop.cloud/api/api/products/6792a4ef-8a55-4e71-8b1c-4e0fae55258c
https://api-shop.beyondshop.cloud/api/api/products/1ceb9d67-6fd0-4cc2-845c-53dcc0b48eda
https://api-shop.beyondshop.cloud/api/api/products/65654b98-b03a-4bab-a9ee-e15ca4ea92b2
'

Example response

HTTP/1.1 201 Created
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Location: https://api-shop.beyondshop.cloud/api/products

List Google Shopping products

Use a GET request to retrieve a list of all Google Shopping products.

Required scopes

gspr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products' -i -H 'Content-Type: application/json' -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_links

Object

See Hypermedia

page

Object

See Pagination

_embedded.products[].visible

Boolean

Indicates if the product is visible in Google Shopping. Can be true or false.

_embedded.products[].category

Number

The category number as defined in the Google taxonomy.

_embedded.products[].status

Object

The status of the product publication process.

_embedded.products[].status.type

String

The status type of the product publication process. Can be INCOMPLETE, READY_FOR_UPLOAD, PENDING, ERROR, PUBLISHED or PUBLISHED_WITH_NOTIFICATIONS.

_embedded.products[].status.errorMessage

Null

The error message for an error that appears during the product publication process. Is null for INCOMPLETE, PENDING, UPLOADED.

_embedded.products[].parentId

String

The unique identifier of the related original product.

_embedded.products[]._id

String

The immutable, unique identifier of the requested resource.

_embedded.products[]._links

Object

See Hypermedia

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 3654

{
  "_embedded" : {
    "products" : [ {
      "visible" : true,
      "category" : 123456,
      "status" : {
        "type" : "INCOMPLETE",
        "errorMessage" : null
      },
      "_id" : "1aa45ba0-7b11-4584-9a9d-94ac32e75f41",
      "parentId" : "ed469948-490e-4b4a-9cc5-bcc4f7df462e",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/1aa45ba0-7b11-4584-9a9d-94ac32e75f41"
        },
        "products" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products{?page,size,sort}",
          "templated" : true
        },
        "product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/products/1f49e78c-abcb-4400-a5de-e1459a17f47a"
        }
      }
    }, {
      "visible" : true,
      "category" : 123456,
      "status" : {
        "type" : "INCOMPLETE",
        "errorMessage" : null
      },
      "_id" : "a7dce951-46b1-4d1f-ae8b-5b343ececd7d",
      "parentId" : "c738df52-a58f-4135-a63f-8e8522ced852",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/a7dce951-46b1-4d1f-ae8b-5b343ececd7d"
        },
        "products" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products{?page,size,sort}",
          "templated" : true
        },
        "product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/products/3a564a09-a3d1-409a-b5a5-d520d8f2ebdf"
        }
      }
    }, {
      "visible" : true,
      "category" : 123456,
      "status" : {
        "type" : "INCOMPLETE",
        "errorMessage" : null
      },
      "_id" : "b7414e9e-6a09-40f3-bf3c-bfd0f38dfcca",
      "parentId" : "a1c5a678-c67b-4d44-87b5-05e36afde81c",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/b7414e9e-6a09-40f3-bf3c-bfd0f38dfcca"
        },
        "products" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products{?page,size,sort}",
          "templated" : true
        },
        "product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/products/23c7b597-1b55-4210-a650-845f380c530d"
        }
      }
    }, {
      "visible" : true,
      "category" : 123456,
      "status" : {
        "type" : "INCOMPLETE",
        "errorMessage" : null
      },
      "_id" : "f20dc193-d53c-48d3-b0d4-76a49d147869",
      "parentId" : "98f6ed41-329e-48d0-ae2f-f6b0a1ce79ba",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/f20dc193-d53c-48d3-b0d4-76a49d147869"
        },
        "products" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products{?page,size,sort}",
          "templated" : true
        },
        "product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/products/fcd98a55-e5d7-470d-89ec-e48adc0ff343"
        }
      }
    }, {
      "visible" : true,
      "category" : 123456,
      "status" : {
        "type" : "INCOMPLETE",
        "errorMessage" : null
      },
      "_id" : "f3cae28a-27fc-4ade-b0fa-59722f10f727",
      "parentId" : "afc97efb-1ac0-4c26-a1e8-e6b7f9e0b7ab",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/f3cae28a-27fc-4ade-b0fa-59722f10f727"
        },
        "products" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products{?page,size,sort}",
          "templated" : true
        },
        "product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/products/c01a1d0d-b350-4457-90b5-9e080de17383"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products{?page,size,sort}",
      "templated" : true
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 5,
    "totalPages" : 1,
    "number" : 0
  }
}

Show Google Shopping product details

Use a GET request to retrieve the details of a Google Shopping product.

Required scopes

gspr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/af26e8a9-c8cd-4778-8d5b-abc8af523cba' -i -H 'Content-Type: application/json' -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

visible

Boolean

Indicates if the product is visible in Google Shopping. Can be true or false.

category

Number

The category number as defined in the Google taxonomy.

status

Object

The status of the product publication process.

status.type

String

The status type of the product publication process. Can be INCOMPLETE, READY_FOR_UPLOAD, PENDING, ERROR, PUBLISHED or PUBLISHED_WITH_NOTIFICATIONS.

status.errorMessage

Null

The error message for an error that appears during the product publication process. Is null for INCOMPLETE, PENDING, UPLOADED.

parentId

String

The unique identifier of the related original product.

_id

String

The immutable, unique identifier of the requested resource.

_links

Object

See Hypermedia

Links

Relation Description

product

The link to the original product.

products

The products that match a product to a Google offer.

publish

The link to publish a product on Google Shopping.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 720

{
  "visible" : true,
  "category" : 123456,
  "status" : {
    "type" : "READY_FOR_UPLOAD",
    "errorMessage" : null
  },
  "_id" : "af26e8a9-c8cd-4778-8d5b-abc8af523cba",
  "parentId" : "fe9446ce-f38f-45bd-827c-96de5efe0c50",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/af26e8a9-c8cd-4778-8d5b-abc8af523cba"
    },
    "products" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products{?page,size,sort}",
      "templated" : true
    },
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/products/de4ffcb8-cc71-4fc9-9372-4e3d7cab36ae"
    },
    "publish" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/products/de4ffcb8-cc71-4fc9-9372-4e3d7cab36ae/publish"
    }
  }
}

Update Google Shopping product

Use a PUT request to update a Google Shopping product.

Required scopes

gspr:u

Request body properties

Path Type Description Constraints

visible

Boolean

Indicates if the product is visible in Google Shopping. Can be true or false.

category

Number

The category number as defined in the Google taxonomy.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/39179b12-87d4-472a-b054-d244c057a25c' -i -X PUT -H 'Content-Type: application/json' -H 'Authorization: Bearer <Access token>' -d '{
  "category" : 111,
  "visible" : true
}'

Response body properties

Path Type Description

visible

Boolean

Indicates if the product is visible in Google Shopping. Can be true or false.

category

Number

The category number as defined in the Google taxonomy.

status

Object

The status of the product publication process.

status.type

String

The status type of the product publication process. Can be INCOMPLETE, READY_FOR_UPLOAD, PENDING, ERROR, PUBLISHED or PUBLISHED_WITH_NOTIFICATIONS.

status.errorMessage

Null

The error message for an error that appears during the product publication process. Is null for INCOMPLETE, PENDING, UPLOADED.

parentId

String

The unique identifier of the related original product.

_id

String

The immutable, unique identifier of the requested resource.

_links

Object

See Hypermedia

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 717

{
  "visible" : true,
  "category" : 111,
  "status" : {
    "type" : "READY_FOR_UPLOAD",
    "errorMessage" : null
  },
  "_id" : "39179b12-87d4-472a-b054-d244c057a25c",
  "parentId" : "2d7fba26-55b3-44bb-95c6-e4d508a3a7f3",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/39179b12-87d4-472a-b054-d244c057a25c"
    },
    "products" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products{?page,size,sort}",
      "templated" : true
    },
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/products/d540ae81-cdf5-425b-bf98-1ec271d98db3"
    },
    "publish" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/products/d540ae81-cdf5-425b-bf98-1ec271d98db3/publish"
    }
  }
}

Remove Google Shopping product

Use a DELETE request to remove a product from Google Shopping.

Required scopes

gspr:d

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/620a3341-476f-450d-8f5c-ed0b2ad8f957' -i -X DELETE -H 'Content-Type: application/json' -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

Publish a list of Google Shopping products

Once Google Shopping products have been added, they can be published on Google Shopping. After publication, the products are available in the Google Merchant Center. It can take up to two hours until the products are listed.

Use a POST request to publish a list of Google Shopping products.

Required scopes

gspr:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/publish' -i -X POST -H 'Content-Type: text/uri-list' -H 'Authorization: Bearer <Access token>' -d 'https://api-shop.beyondshop.cloud/api/api/google-shopping/products/7ce77a8a-5640-4c12-88b6-4293cba2014d
https://api-shop.beyondshop.cloud/api/api/google-shopping/products/6e4b2320-7300-415d-b4ef-0b4d0918a251
https://api-shop.beyondshop.cloud/api/api/google-shopping/products/0c74c74b-4d90-4a5b-a27c-cac1c79c89ce
https://api-shop.beyondshop.cloud/api/api/google-shopping/products/f6ce2c21-45f6-42e5-815c-74cc1845a349
https://api-shop.beyondshop.cloud/api/api/google-shopping/products/c68863f3-07df-4355-8f27-a07e865b1efa
'

Example response

HTTP/1.1 202 Accepted
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

Publish individual Google Shopping product

Once a Google Shopping product has been added, it can be published on Google Shopping. After publication, the product is available in the Google Merchant Center. It can take up to two hours until the product is listed.

Use a POST request to publish an individual Google Shopping product.

Required scopes

gspr:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/3ce424ea-9a96-43b1-82ac-2cfc304a12fe/publish' -i -X POST -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 717

{
  "visible" : true,
  "category" : 123456,
  "status" : {
    "type" : "PUBLISHED",
    "errorMessage" : null
  },
  "_id" : "3ce424ea-9a96-43b1-82ac-2cfc304a12fe",
  "parentId" : "92a97b1a-dd0c-4110-98f2-2249583051d7",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/3ce424ea-9a96-43b1-82ac-2cfc304a12fe"
    },
    "products" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products{?page,size,sort}",
      "templated" : true
    },
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/products/de4ffcb8-cc71-4fc9-9372-4e3d7cab36ae"
    },
    "unpublish" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/products/de4ffcb8-cc71-4fc9-9372-4e3d7cab36ae/unpublish"
    }
  }
}

Unpublish individual Google Shopping product

Use a POST request to unpublish a product from Google Shopping. Once unpublished, it will disappear from the Google Merchant Center, but will still be available with the READY_FOR_UPLOAD status.

Required scopes

gspr:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/3c0e260a-992f-49ff-bb02-b1d666fa03ca/unpublish' -i -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 720

{
  "visible" : true,
  "category" : 123456,
  "status" : {
    "type" : "READY_FOR_UPLOAD",
    "errorMessage" : null
  },
  "_id" : "3c0e260a-992f-49ff-bb02-b1d666fa03ca",
  "parentId" : "dbc20083-2c85-496e-afcc-57eee5669b63",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/3c0e260a-992f-49ff-bb02-b1d666fa03ca"
    },
    "products" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products{?page,size,sort}",
      "templated" : true
    },
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/products/de4ffcb8-cc71-4fc9-9372-4e3d7cab36ae"
    },
    "publish" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/products/de4ffcb8-cc71-4fc9-9372-4e3d7cab36ae/publish"
    }
  }
}

Taxonomy

List taxonomy

The taxonomy contains the available Google categories to be assigned to a product to publish to Google.

Use a GET request to retrieve the current taxonomy from Google.

Request parameters

Parameter Description

locale

The locale determining the localization context, i.e. the language of the Google taxonomy.

Request header properties

Name Description

if-modified-since

The date of the last successful retrieval of the Google taxonomy. Optional. If not set the current version of the Google taxonomy is always returned.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/taxonomy?locale=de-DE' -i -H 'if-modified-since: Thu, 07 Dec 2016 01:00:57 GMT'

Response body properties

Path Type Description

_embedded.googleCategories

Array

The list of Google Shopping categories.

_embedded.googleCategories[].categoryId

Number

The Google Shopping category id.

_embedded.googleCategories[].categoryName

String

The Google Shopping category name.

_embedded.googleCategories[].children

Array

The subcategories of the Google Shopping category.

_links

Object

See Hypermedia

Example response

HTTP/1.1 200 OK
Last-Modified: Thu, 08 Dec 2016 01:00:57 GMT
Content-Type: application/json
Content-Length: 605

{
  "_embedded" : {
    "googleCategories" : [ {
      "categoryId" : 1,
      "categoryName" : "Category1",
      "children" : [ ]
    }, {
      "categoryId" : 2,
      "categoryName" : "Category2",
      "children" : [ ]
    }, {
      "categoryId" : 3,
      "categoryName" : "Category3",
      "children" : [ ]
    }, {
      "categoryId" : 4,
      "categoryName" : "Category4",
      "children" : [ ]
    }, {
      "categoryId" : 5,
      "categoryName" : "Category5",
      "children" : [ ]
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/taxonomy"
    }
  }
}

Site Verification Token

Retrieve site verification token

The site verification token required to verify that a shop really belongs to that specific merchant. The site verification token has to be available on the storefront, in order for Google to know that this site really belongs to the Google Shopping merchant.

Use a GET request to retrieve the site verification token.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/site-verification' -i

Response body properties

Path Type Description

token

String

The site verification token required to verify that a shop really belongs to that specific merchant.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/json;charset=UTF-8
Content-Length: 38

{
  "token" : "<verification token>"
}

Orders

Order number configuration

This resource gives the merchant control over the structure of order numbers.

A prefix can be defined for the order number as well as a numeric suffix to start counting from. The length of the numeric suffix can also be configured.

Such a configuration

  • prefix = 2017-shop-

  • next numeric suffix = 1000

  • numeric suffix length = 5

results in an order number like 2017-shop-01000. Where the numeric suffix is increased for every order.

Show order number configuration details

A GET request is used to retrieve the order number configuration for the current shop.

Required scopes

ordn:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/configuration/order-number' -i -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_links

Object

See Hypermedia

stringPrefix

String

prefix attached to all order numbers

nextNumericSuffix

Number

the next numeric suffix used for the next order. This value is incremented after each order creation

numericSuffixLength

Number

the length of the numeric part of the order number. If the numeric value is shorter, the value is padded with zeros to the left. If the value is longer the numericSuffixLength is extended

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 195

{
  "stringPrefix" : "",
  "nextNumericSuffix" : 10001,
  "numericSuffixLength" : 5,
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/configuration/order-number"
    }
  }
}

Update complete order number configuration

A PUT request is used to update the complete order number configuration for the current shop.

Required scopes

ordn:u

Request body properties

Path Type Description Constraints

stringPrefix

String

prefix attached to all order numbers

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

nextNumericSuffix

Number

the next numeric suffix used for the next order. This value is incremented after each order creation

Must be greater than 0 and less than 9223372036854775807

numericSuffixLength

Number

the length of the numeric part of the order number. If the numeric value is shorter, the value is padded with zeros to the left. If the value is longer the numericSuffixLength is extended

Must be greater than 0 and less than 20

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/configuration/order-number' -i -X PUT -H 'Content-Type: application/json' -H 'Authorization: Bearer <Access token>' -d '{
  "stringPrefix" : "2017-shop-",
  "nextNumericSuffix" : 10000,
  "numericSuffixLength" : 4
}'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 205

{
  "stringPrefix" : "2017-shop-",
  "nextNumericSuffix" : 10000,
  "numericSuffixLength" : 4,
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/configuration/order-number"
    }
  }
}

Update order number configuration partially

A PATCH request is used to update parts of the order number configuration for the current shop.

Patch can be applied using json-patch or plain json.

All fields updatable via PUT can be updated using patch

Required scopes

ordn:u

Request body properties

Path Type Description

[]

Array

list of json patch operations as defined in https://tools.ietf.org/html/rfc6902.All fields updatable via PUT can be updated using patch

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/configuration/order-number' -i -X PATCH -H 'Content-Type: application/json-patch+json' -H 'Authorization: Bearer <Access token>' -d '[ {
  "op" : "replace",
  "path" : "/stringPrefix",
  "value" : "2017-shop-"
}, {
  "op" : "replace",
  "path" : "/nextNumericSuffix",
  "value" : 20000
} ]'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 205

{
  "stringPrefix" : "2017-shop-",
  "nextNumericSuffix" : 20000,
  "numericSuffixLength" : 5,
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/configuration/order-number"
    }
  }
}

Required scopes

ordn:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/configuration/order-number' -i -X PATCH -H 'Content-Type: application/json' -H 'Authorization: Bearer <Access token>' -d '{
  "stringPrefix" : "2017-shop-",
  "nextNumericSuffix" : 20000
}'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 205

{
  "stringPrefix" : "2017-shop-",
  "nextNumericSuffix" : 20000,
  "numericSuffixLength" : 5,
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/configuration/order-number"
    }
  }
}

The orders resource is used to manage the orders of a shop.

List orders

A GET request will list all of the 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 -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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 11233

{
  "_embedded" : {
    "orders" : [ {
      "_id" : "3b03465e-c949-4a77-8475-c2bc41490ecd",
      "createdAt" : "2018-02-06T09:16:36.453",
      "cartId" : "9249adf0-61ca-4011-a9a5-b3ee85e74e8f",
      "currency" : "EUR",
      "taxModel" : "GROSS",
      "taxable" : false,
      "testOrder" : false,
      "productLineItems" : [ {
        "product" : {
          "sku" : "1018",
          "name" : "Decorative Sand (2 kg Jumbo Pack)",
          "essentialFeatures" : "Not suitable for children under the age of 8.",
          "shippingWeight" : 2000,
          "defaultImageDataUri" : "/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
          "_id" : "463591c5-63e2-49ab-b83e-fcfa9fb277c3",
          "_links" : {
            "default-image-data" : {
              "href" : "https://api-shop.beyondshop.cloud/api/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
              "templated" : true
            }
          }
        },
        "quantity" : {
          "value" : 5,
          "unit" : "PIECE"
        },
        "quantityInt" : 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" : "22d51caf-2706-42ae-9456-a2aa4dd14653"
      }, {
        "product" : {
          "sku" : "1004",
          "name" : "White Sofa",
          "essentialFeatures" : null,
          "shippingWeight" : null,
          "defaultImageDataUri" : "/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
          "_id" : "f68f78b8-eea1-4d37-af53-70d00c1cd1c2",
          "_links" : {
            "default-image-data" : {
              "href" : "https://api-shop.beyondshop.cloud/api/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
              "templated" : true
            }
          }
        },
        "quantity" : {
          "value" : 3,
          "unit" : "PIECE"
        },
        "quantityInt" : 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" : "5c8b7db8-739a-47fc-8012-a86cf633d3c4"
      } ],
      "shippingLineItem" : {
        "lineItemPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 16.95
        },
        "initialLineItemPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 16.95
        },
        "taxClass" : "REGULAR",
        "shippingMethod" : {
          "name" : "Standard Shipping",
          "description" : "Standard Shipping",
          "freeShippingValue" : {
            "currency" : "EUR",
            "amount" : 100
          },
          "fixedPrice" : {
            "taxModel" : "GROSS",
            "currency" : "EUR",
            "amount" : 16.95
          },
          "weightBasedPrice" : null
        },
        "lineItemTaxes" : [ {
          "taxClass" : "REGULAR",
          "taxRate" : 0.19,
          "currency" : "EUR",
          "amount" : 2.7056
        } ]
      },
      "paymentLineItem" : {
        "lineItemPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 0
        },
        "initialLineItemPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 0
        },
        "taxClass" : "REGULAR",
        "paymentMethod" : {
          "name" : "PayPal",
          "description" : "Pay with 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
        } ]
      },
      "subtotal" : {
        "currency" : "EUR",
        "amount" : 57.45
      },
      "grandTotal" : {
        "currency" : "EUR",
        "amount" : 74.4
      },
      "balanceDue" : {
        "currency" : "EUR",
        "amount" : 74.4
      },
      "netTotal" : {
        "currency" : "EUR",
        "amount" : 65.2287
      },
      "taxTotal" : {
        "currency" : "EUR",
        "amount" : 9.1713
      },
      "initialSubtotal" : {
        "currency" : "EUR",
        "amount" : 57.45
      },
      "initialGrandTotal" : {
        "currency" : "EUR",
        "amount" : 74.4
      },
      "initialBalanceDue" : {
        "currency" : "EUR",
        "amount" : 74.4
      },
      "initialNetTotal" : {
        "currency" : "EUR",
        "amount" : 65.2287
      },
      "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" : "1st floor",
        "addressExtension" : "c/o Astrid Alster",
        "postalCode" : "20999",
        "city" : "Alsterwasser",
        "country" : "DE",
        "state" : "Hamburg",
        "email" : "a@example.com",
        "phone" : "(800) 555-0100",
        "mobile" : "(800) 555-0101",
        "doorCode" : "456",
        "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "1st floor", "20999 Alsterwasser" ]
      },
      "billingAddress" : {
        "salutation" : "Mrs",
        "gender" : "FEMALE",
        "company" : "Astrid Alster GmbH",
        "title" : null,
        "firstName" : "Astrid",
        "middleName" : "Agnes",
        "lastName" : "Alster",
        "street" : "Alsterwasserweg",
        "houseNumber" : "2",
        "street2" : "1st floor",
        "addressExtension" : "c/o Astrid Alster",
        "postalCode" : "20999",
        "city" : "Alsterwasser",
        "country" : "DE",
        "state" : "Hamburg",
        "email" : "a@example.com",
        "phone" : "(800) 555-0100",
        "mobile" : "(800) 555-0101",
        "vatId" : "DE123456789",
        "taxNumber" : "HRE 987654/32123/864516",
        "birthDate" : "1985-05-11",
        "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "1st floor", "20999 Alsterwasser" ]
      },
      "paymentStatus" : "PENDING",
      "shippingStatus" : "UNSHIPPED",
      "canceled" : false,
      "orderNumber" : "10001",
      "customerComment" : null,
      "orderNote" : "not paid yet",
      "entryDate" : "2018-02-06T09:16:36.453",
      "totalReceived" : {
        "currency" : "EUR",
        "amount" : 0
      },
      "totalRefunded" : {
        "currency" : "EUR",
        "amount" : 0
      },
      "openAmount" : {
        "currency" : "EUR",
        "amount" : 74.4
      },
      "marketingChannel" : "Google shopping",
      "marketingSubchannel" : "Some category",
      "salesChannel" : "Storefront",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/3b03465e-c949-4a77-8475-c2bc41490ecd"
        },
        "order" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/3b03465e-c949-4a77-8475-c2bc41490ecd"
        },
        "order-note" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/3b03465e-c949-4a77-8475-c2bc41490ecd/order-note"
        },
        "processes" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/3b03465e-c949-4a77-8475-c2bc41490ecd/processes"
        },
        "events" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/3b03465e-c949-4a77-8475-c2bc41490ecd/events"
        },
        "cancel" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/3b03465e-c949-4a77-8475-c2bc41490ecd/cancel"
        },
        "order-receipt-pdf" : {
          "href" : "https://api-shop.beyondshop.cloud/api/order.receipt/uri.pdf"
        },
        "create-invoice" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/3b03465e-c949-4a77-8475-c2bc41490ecd/create-invoice"
        },
        "terms-and-conditions-pdf" : {
          "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/some.pdf?hash=23213"
        },
        "right-of-withdrawal-pdf" : {
          "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/some.pdf?hash=23213"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders?page=0&size=20"
    }
  },
  "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/cfb572e9-bfdb-4791-b41b-db3a223f4dd6' -i -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/in another system.

entryDate

String

The date and time of the actual creation date 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.

orderNumber

String

The order number generated by the order service.

customerComment

Null

A comment from the customer regarding their order.

salesChannel

String

The sales channel of this order.

marketingChannel

String

The marketing channel of this order.

marketingSubchannel

String

The marketing subchannel of this order.

productLineItems[].quantity.value

Number

The value of the quantity for the product line item.

productLineItems[].quantity.unit

String

The unit corresponding to the quantity for the product line item.

productLineItems[].quantityInt

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.

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

Varies

The essential product properties of the product in this product line item.

productLineItems[].product.shippingWeight

Varies

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.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 items of this product line item that are not yet dispatched.

productLineItems[].unshipped.amount

Null

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

productLineItems[].shipped.quantity

Number

The quantity of dispatched items of this product line item.

productLineItems[].shipped.amount

Null

The amount of the 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 the 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 the 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 the 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 the canceled items of this product line item.

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.

shippingLineItem.lineItemTaxes

Array

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

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 {{values}}.

paymentLineItem.lineItemTaxes

Array

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

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 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 total amount 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 open amount.

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.

taxes

Array

The taxes grouped by tax class.

taxes[*].taxClass

String

The tax class.

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.

canceled

Boolean

The current cancelation status of this order. Can be {{values}}.

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.

order-receipt-pdf

The link to the order receipt pdf (exists if the document has already been created).

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.

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.

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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 9492

{
  "_id" : "cfb572e9-bfdb-4791-b41b-db3a223f4dd6",
  "createdAt" : "2018-02-06T09:16:35.108",
  "cartId" : "1abd615b-ba71-4233-b411-3dac8e543cbb",
  "currency" : "EUR",
  "taxModel" : "GROSS",
  "taxable" : false,
  "testOrder" : false,
  "productLineItems" : [ {
    "product" : {
      "sku" : "1004",
      "name" : "White Sofa",
      "essentialFeatures" : null,
      "shippingWeight" : null,
      "defaultImageDataUri" : "/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "_id" : "5e3e1492-5a5c-4a06-88e5-6987a6a9d97c",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
          "templated" : true
        }
      }
    },
    "quantity" : {
      "value" : 3,
      "unit" : "PIECE"
    },
    "quantityInt" : 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" : "53d0d482-6a20-4254-960c-d39539acdde7"
  }, {
    "product" : {
      "sku" : "1018",
      "name" : "Decorative Sand (2 kg Jumbo Pack)",
      "essentialFeatures" : "Not suitable for children under the age of 8.",
      "shippingWeight" : 2000,
      "defaultImageDataUri" : "/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "_id" : "60498ec2-dc7d-4543-b7f8-68e36478c1ec",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
          "templated" : true
        }
      }
    },
    "quantity" : {
      "value" : 5,
      "unit" : "PIECE"
    },
    "quantityInt" : 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" : "563c8c30-2105-418b-bdf5-ab75a4c28de4"
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "taxClass" : "REGULAR",
    "shippingMethod" : {
      "name" : "Standard Shipping",
      "description" : "Standard Shipping",
      "freeShippingValue" : {
        "currency" : "EUR",
        "amount" : 100
      },
      "fixedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 16.95
      },
      "weightBasedPrice" : null
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 2.7056
    } ]
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "taxClass" : "REGULAR",
    "paymentMethod" : {
      "name" : "PayPal",
      "description" : "Pay with 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
    } ]
  },
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 65.2287
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 9.1713
  },
  "initialSubtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "initialGrandTotal" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "initialBalanceDue" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "initialNetTotal" : {
    "currency" : "EUR",
    "amount" : 65.2287
  },
  "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" : "1st floor",
    "addressExtension" : "c/o Astrid Alster",
    "postalCode" : "20999",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a@example.com",
    "phone" : "(800) 555-0100",
    "mobile" : "(800) 555-0101",
    "doorCode" : "456",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "1st floor", "20999 Alsterwasser" ]
  },
  "billingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "1st floor",
    "addressExtension" : "c/o Astrid Alster",
    "postalCode" : "20999",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a@example.com",
    "phone" : "(800) 555-0100",
    "mobile" : "(800) 555-0101",
    "vatId" : "DE123456789",
    "taxNumber" : "HRE 987654/32123/864516",
    "birthDate" : "1985-05-11",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "1st floor", "20999 Alsterwasser" ]
  },
  "paymentStatus" : "PENDING",
  "shippingStatus" : "UNSHIPPED",
  "canceled" : false,
  "orderNumber" : "10001",
  "customerComment" : null,
  "orderNote" : "not paid yet",
  "entryDate" : "2018-02-06T09:16:35.108",
  "totalReceived" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "totalRefunded" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "openAmount" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "marketingChannel" : "Google shopping",
  "marketingSubchannel" : "Some category",
  "salesChannel" : "Storefront",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/cfb572e9-bfdb-4791-b41b-db3a223f4dd6"
    },
    "order" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/cfb572e9-bfdb-4791-b41b-db3a223f4dd6"
    },
    "order-note" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/cfb572e9-bfdb-4791-b41b-db3a223f4dd6/order-note"
    },
    "processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/cfb572e9-bfdb-4791-b41b-db3a223f4dd6/processes"
    },
    "events" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/cfb572e9-bfdb-4791-b41b-db3a223f4dd6/events"
    },
    "cancel" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/cfb572e9-bfdb-4791-b41b-db3a223f4dd6/cancel"
    },
    "order-receipt-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/order.receipt/uri.pdf"
    },
    "create-invoice" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/cfb572e9-bfdb-4791-b41b-db3a223f4dd6/create-invoice"
    },
    "right-of-withdrawal-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/some.pdf?hash=23213"
    },
    "terms-and-conditions-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/some.pdf?hash=23213"
    }
  }
}

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=33889615-baf4-4f9d-ba93-a8c437573d96' -i -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 9492

{
  "_id" : "a3c4f173-434f-418c-ad6b-d5b68d912470",
  "createdAt" : "2018-02-06T09:16:27.478",
  "cartId" : "33889615-baf4-4f9d-ba93-a8c437573d96",
  "currency" : "EUR",
  "taxModel" : "GROSS",
  "taxable" : false,
  "testOrder" : false,
  "productLineItems" : [ {
    "product" : {
      "sku" : "1004",
      "name" : "White Sofa",
      "essentialFeatures" : null,
      "shippingWeight" : null,
      "defaultImageDataUri" : "/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "_id" : "4b1ca5a6-e2b0-4490-a039-2976841f5ddd",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
          "templated" : true
        }
      }
    },
    "quantity" : {
      "value" : 3,
      "unit" : "PIECE"
    },
    "quantityInt" : 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" : "b893f3df-a63a-4ed6-948e-565297ebd505"
  }, {
    "product" : {
      "sku" : "1018",
      "name" : "Decorative Sand (2 kg Jumbo Pack)",
      "essentialFeatures" : "Not suitable for children under the age of 8.",
      "shippingWeight" : 2000,
      "defaultImageDataUri" : "/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "_id" : "b9a38e9b-62d5-4c5c-ac9d-c5ccf7c9bd1e",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
          "templated" : true
        }
      }
    },
    "quantity" : {
      "value" : 5,
      "unit" : "PIECE"
    },
    "quantityInt" : 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" : "b9c21ac9-1bb2-45e3-bbb2-677e47cc6309"
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "taxClass" : "REGULAR",
    "shippingMethod" : {
      "name" : "Standard Shipping",
      "description" : "Standard Shipping",
      "freeShippingValue" : {
        "currency" : "EUR",
        "amount" : 100
      },
      "fixedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 16.95
      },
      "weightBasedPrice" : null
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 2.7056
    } ]
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "taxClass" : "REGULAR",
    "paymentMethod" : {
      "name" : "PayPal",
      "description" : "Pay with 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
    } ]
  },
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 65.2287
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 9.1713
  },
  "initialSubtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "initialGrandTotal" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "initialBalanceDue" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "initialNetTotal" : {
    "currency" : "EUR",
    "amount" : 65.2287
  },
  "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" : "1st floor",
    "addressExtension" : "c/o Astrid Alster",
    "postalCode" : "20999",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a@example.com",
    "phone" : "(800) 555-0100",
    "mobile" : "(800) 555-0101",
    "doorCode" : "456",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "1st floor", "20999 Alsterwasser" ]
  },
  "billingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "1st floor",
    "addressExtension" : "c/o Astrid Alster",
    "postalCode" : "20999",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a@example.com",
    "phone" : "(800) 555-0100",
    "mobile" : "(800) 555-0101",
    "vatId" : "DE123456789",
    "taxNumber" : "HRE 987654/32123/864516",
    "birthDate" : "1985-05-11",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "1st floor", "20999 Alsterwasser" ]
  },
  "paymentStatus" : "PENDING",
  "shippingStatus" : "UNSHIPPED",
  "canceled" : false,
  "orderNumber" : "10001",
  "customerComment" : null,
  "orderNote" : "not paid yet",
  "entryDate" : "2018-02-06T09:16:27.478",
  "totalReceived" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "totalRefunded" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "openAmount" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "marketingChannel" : "Google shopping",
  "marketingSubchannel" : "Some category",
  "salesChannel" : "Storefront",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/a3c4f173-434f-418c-ad6b-d5b68d912470"
    },
    "order" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/a3c4f173-434f-418c-ad6b-d5b68d912470"
    },
    "order-note" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/a3c4f173-434f-418c-ad6b-d5b68d912470/order-note"
    },
    "processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/a3c4f173-434f-418c-ad6b-d5b68d912470/processes"
    },
    "events" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/a3c4f173-434f-418c-ad6b-d5b68d912470/events"
    },
    "cancel" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/a3c4f173-434f-418c-ad6b-d5b68d912470/cancel"
    },
    "order-receipt-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/order.receipt/uri.pdf"
    },
    "create-invoice" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/a3c4f173-434f-418c-ad6b-d5b68d912470/create-invoice"
    },
    "right-of-withdrawal-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/some.pdf?hash=23213"
    },
    "terms-and-conditions-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/some.pdf?hash=23213"
    }
  }
}

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/38d2f109-c72e-427d-9c5b-70d0e29ec684/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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 7366

{
  "createdAt" : "2018-02-06T09:16:37.425",
  "cartId" : "85abe305-3029-4991-a4e5-e995589097ed",
  "currency" : "EUR",
  "taxModel" : "GROSS",
  "taxable" : false,
  "testOrder" : false,
  "productLineItems" : [ {
    "quantity" : {
      "value" : 5,
      "unit" : "PIECE"
    },
    "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" : {
      "sku" : "1018",
      "name" : "Decorative Sand (2 kg Jumbo Pack)",
      "essentialFeatures" : "Not suitable for children under the age of 8.",
      "shippingWeight" : 2000,
      "defaultImageDataUri" : "/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "_id" : "d3d103ff-bd43-44ce-b998-d849ea38efa3",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
          "templated" : true
        }
      }
    },
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 7.9743
    },
    "quantityInt" : 5
  }, {
    "quantity" : {
      "value" : 3,
      "unit" : "PIECE"
    },
    "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" : {
      "sku" : "1004",
      "name" : "White Sofa",
      "essentialFeatures" : null,
      "shippingWeight" : null,
      "defaultImageDataUri" : "/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "_id" : "d28cfa72-f770-4e8f-91d1-9359e38dd0f0",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
          "templated" : true
        }
      }
    },
    "lineItemTax" : {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 1.197
    },
    "quantityInt" : 3
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "taxClass" : "REGULAR",
    "shippingMethod" : {
      "name" : "Standard Shipping",
      "description" : "Standard Shipping",
      "freeShippingValue" : {
        "currency" : "EUR",
        "amount" : 100
      },
      "fixedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 16.95
      },
      "weightBasedPrice" : null
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 2.7056
    } ]
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "taxClass" : "REGULAR",
    "paymentMethod" : {
      "name" : "PayPal",
      "description" : "Pay with 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
    } ]
  },
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "initialSubtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "initialGrandTotal" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "initialBalanceDue" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 65.2287
  },
  "initialNetTotal" : {
    "currency" : "EUR",
    "amount" : 65.2287
  },
  "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" : "1st floor",
    "addressExtension" : "c/o Astrid Alster",
    "postalCode" : "20999",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a@example.com",
    "phone" : "(800) 555-0100",
    "mobile" : "(800) 555-0101",
    "doorCode" : "456",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "1st floor", "20999 Alsterwasser" ]
  },
  "billingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "1st floor",
    "addressExtension" : "c/o Astrid Alster",
    "postalCode" : "20999",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a@example.com",
    "phone" : "(800) 555-0100",
    "mobile" : "(800) 555-0101",
    "vatId" : "DE123456789",
    "taxNumber" : "HRE 987654/32123/864516",
    "birthDate" : "1985-05-11",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "1st floor", "20999 Alsterwasser" ]
  },
  "customerComment" : null,
  "orderNote" : "not paid yet",
  "orderReceiptPdfUri" : "order.receipt/uri.pdf",
  "invoicePdfUri" : null,
  "entryDate" : "2018-02-06T09:16:37.425",
  "marketingChannel" : "Google shopping",
  "marketingSubchannel" : "Some category",
  "salesChannel" : "Storefront",
  "shippingStatus" : "UNSHIPPED",
  "totalReceived" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "totalRefunded" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "openAmount" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "paymentStatus" : "PENDING",
  "canceled" : false,
  "_id" : "38d2f109-c72e-427d-9c5b-70d0e29ec684",
  "orderNumber" : "10001",
  "invoiceNumber" : "10001",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/38d2f109-c72e-427d-9c5b-70d0e29ec684"
    },
    "order" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/38d2f109-c72e-427d-9c5b-70d0e29ec684"
    }
  }
}

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/6a858d48-131a-42e7-8501-b8727289763b/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" : "1st floor",
    "addressExtension" : "c/o Astrid Alster",
    "postalCode" : "20999",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a@example.com",
    "phone" : "(800) 555-0100",
    "mobile" : "(800) 555-0101",
    "vatId" : "DE123456789",
    "taxNumber" : "HRE 987654/32123/864516",
    "birthDate" : "1985-05-11",
    "displayAddressLines" : [ null, "null null null", "null null", null, "null null" ],
    "_id" : null
  },
  "comment" : "Updated billing address"
}'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 9500

{
  "_id" : "6a858d48-131a-42e7-8501-b8727289763b",
  "createdAt" : "2018-02-06T09:16:29.154",
  "cartId" : "e4a5a5e2-e97d-43b5-a7a9-d38b43896a8a",
  "currency" : "EUR",
  "taxModel" : "GROSS",
  "taxable" : false,
  "testOrder" : false,
  "productLineItems" : [ {
    "product" : {
      "sku" : "1004",
      "name" : "White Sofa",
      "essentialFeatures" : null,
      "shippingWeight" : null,
      "defaultImageDataUri" : "/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "_id" : "4752d273-fb9d-424b-8cbd-b72fadb6d820",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
          "templated" : true
        }
      }
    },
    "quantity" : {
      "value" : 3,
      "unit" : "PIECE"
    },
    "quantityInt" : 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" : "3501c062-0a8d-4216-96b7-9f635eaf38de"
  }, {
    "product" : {
      "sku" : "1018",
      "name" : "Decorative Sand (2 kg Jumbo Pack)",
      "essentialFeatures" : "Not suitable for children under the age of 8.",
      "shippingWeight" : 2000,
      "defaultImageDataUri" : "/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "_id" : "e008ebde-e2b1-42d7-b4bc-a24270e7fe8b",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
          "templated" : true
        }
      }
    },
    "quantity" : {
      "value" : 5,
      "unit" : "PIECE"
    },
    "quantityInt" : 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" : "b2b83829-2576-4785-9691-dd6e0124c564"
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "taxClass" : "REGULAR",
    "shippingMethod" : {
      "name" : "Standard Shipping",
      "description" : "Standard Shipping",
      "freeShippingValue" : {
        "currency" : "EUR",
        "amount" : 100
      },
      "fixedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 16.95
      },
      "weightBasedPrice" : null
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 2.7056
    } ]
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "taxClass" : "REGULAR",
    "paymentMethod" : {
      "name" : "PayPal",
      "description" : "Pay with 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
    } ]
  },
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 65.2287
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 9.1713
  },
  "initialSubtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "initialGrandTotal" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "initialBalanceDue" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "initialNetTotal" : {
    "currency" : "EUR",
    "amount" : 65.2287
  },
  "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" : "1st floor",
    "addressExtension" : "c/o Astrid Alster",
    "postalCode" : "20999",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a@example.com",
    "phone" : "(800) 555-0100",
    "mobile" : "(800) 555-0101",
    "doorCode" : "456",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "1st floor", "20999 Alsterwasser" ]
  },
  "billingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserstraße",
    "houseNumber" : "3",
    "street2" : "1st floor",
    "addressExtension" : "c/o Astrid Alster",
    "postalCode" : "20999",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a@example.com",
    "phone" : "(800) 555-0100",
    "mobile" : "(800) 555-0101",
    "vatId" : "DE123456789",
    "taxNumber" : "HRE 987654/32123/864516",
    "birthDate" : "1985-05-11",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserstraße 3", "1st floor", "20999 Alsterwasser" ]
  },
  "paymentStatus" : "PENDING",
  "shippingStatus" : "UNSHIPPED",
  "canceled" : false,
  "orderNumber" : "10001",
  "customerComment" : null,
  "orderNote" : "not paid yet",
  "entryDate" : "2018-02-06T09:16:29.154",
  "totalReceived" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "totalRefunded" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "openAmount" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "marketingChannel" : "Google shopping",
  "marketingSubchannel" : "Some category",
  "salesChannel" : "Storefront",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/6a858d48-131a-42e7-8501-b8727289763b"
    },
    "order" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/6a858d48-131a-42e7-8501-b8727289763b"
    },
    "order-note" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/6a858d48-131a-42e7-8501-b8727289763b/order-note"
    },
    "processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/6a858d48-131a-42e7-8501-b8727289763b/processes"
    },
    "events" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/6a858d48-131a-42e7-8501-b8727289763b/events"
    },
    "cancel" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/6a858d48-131a-42e7-8501-b8727289763b/cancel"
    },
    "order-receipt-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/order.receipt/uri.pdf"
    },
    "create-invoice" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/6a858d48-131a-42e7-8501-b8727289763b/create-invoice"
    },
    "right-of-withdrawal-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/some.pdf?hash=23213"
    },
    "terms-and-conditions-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/some.pdf?hash=23213"
    }
  }
}

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/e3d3a4c1-f46c-449a-b308-c2fde3e1db0e/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" : "1st floor",
    "addressExtension" : "c/o Astrid Alster",
    "postalCode" : "20999",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a@example.com",
    "phone" : "(800) 555-0100",
    "mobile" : "(800) 555-0101",
    "doorCode" : "456",
    "displayAddressLines" : [ null, "null null null", "null null", null, "null null" ],
    "_id" : null
  },
  "comment" : "Updated shipping address"
}'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 9500

{
  "_id" : "e3d3a4c1-f46c-449a-b308-c2fde3e1db0e",
  "createdAt" : "2018-02-06T09:16:32.863",
  "cartId" : "92f60dc3-2ff6-43b9-ae4c-5eba900b8637",
  "currency" : "EUR",
  "taxModel" : "GROSS",
  "taxable" : false,
  "testOrder" : false,
  "productLineItems" : [ {
    "product" : {
      "sku" : "1018",
      "name" : "Decorative Sand (2 kg Jumbo Pack)",
      "essentialFeatures" : "Not suitable for children under the age of 8.",
      "shippingWeight" : 2000,
      "defaultImageDataUri" : "/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "_id" : "1127662c-da24-4981-94d6-21c1e1396607",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
          "templated" : true
        }
      }
    },
    "quantity" : {
      "value" : 5,
      "unit" : "PIECE"
    },
    "quantityInt" : 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" : "136d2ceb-8cd6-4001-8459-734740620d51"
  }, {
    "product" : {
      "sku" : "1004",
      "name" : "White Sofa",
      "essentialFeatures" : null,
      "shippingWeight" : null,
      "defaultImageDataUri" : "/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "_id" : "4dc31a6c-975b-4791-9e00-2f2e83a69671",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
          "templated" : true
        }
      }
    },
    "quantity" : {
      "value" : 3,
      "unit" : "PIECE"
    },
    "quantityInt" : 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" : "e95bdba3-652c-4b3f-a4ba-7073e7d31710"
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "taxClass" : "REGULAR",
    "shippingMethod" : {
      "name" : "Standard Shipping",
      "description" : "Standard Shipping",
      "freeShippingValue" : {
        "currency" : "EUR",
        "amount" : 100
      },
      "fixedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 16.95
      },
      "weightBasedPrice" : null
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 2.7056
    } ]
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "taxClass" : "REGULAR",
    "paymentMethod" : {
      "name" : "PayPal",
      "description" : "Pay with 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
    } ]
  },
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 65.2287
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 9.1713
  },
  "initialSubtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "initialGrandTotal" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "initialBalanceDue" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "initialNetTotal" : {
    "currency" : "EUR",
    "amount" : 65.2287
  },
  "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" : "1st floor",
    "addressExtension" : "c/o Astrid Alster",
    "postalCode" : "20999",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a@example.com",
    "phone" : "(800) 555-0100",
    "mobile" : "(800) 555-0101",
    "doorCode" : "456",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserstraße 3", "1st floor", "20999 Alsterwasser" ]
  },
  "billingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "1st floor",
    "addressExtension" : "c/o Astrid Alster",
    "postalCode" : "20999",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a@example.com",
    "phone" : "(800) 555-0100",
    "mobile" : "(800) 555-0101",
    "vatId" : "DE123456789",
    "taxNumber" : "HRE 987654/32123/864516",
    "birthDate" : "1985-05-11",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "1st floor", "20999 Alsterwasser" ]
  },
  "paymentStatus" : "PENDING",
  "shippingStatus" : "UNSHIPPED",
  "canceled" : false,
  "orderNumber" : "10001",
  "customerComment" : null,
  "orderNote" : "not paid yet",
  "entryDate" : "2018-02-06T09:16:32.863",
  "totalReceived" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "totalRefunded" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "openAmount" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "marketingChannel" : "Google shopping",
  "marketingSubchannel" : "Some category",
  "salesChannel" : "Storefront",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/e3d3a4c1-f46c-449a-b308-c2fde3e1db0e"
    },
    "order" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/e3d3a4c1-f46c-449a-b308-c2fde3e1db0e"
    },
    "order-note" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/e3d3a4c1-f46c-449a-b308-c2fde3e1db0e/order-note"
    },
    "processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/e3d3a4c1-f46c-449a-b308-c2fde3e1db0e/processes"
    },
    "events" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/e3d3a4c1-f46c-449a-b308-c2fde3e1db0e/events"
    },
    "cancel" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/e3d3a4c1-f46c-449a-b308-c2fde3e1db0e/cancel"
    },
    "order-receipt-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/order.receipt/uri.pdf"
    },
    "create-invoice" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/e3d3a4c1-f46c-449a-b308-c2fde3e1db0e/create-invoice"
    },
    "right-of-withdrawal-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/some.pdf?hash=23213"
    },
    "terms-and-conditions-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/some.pdf?hash=23213"
    }
  }
}

Create invoice

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

Required scopes

ordr:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/870cf264-97b0-40fb-95fb-8c7759c74753/create-invoice' -i -X POST -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 9498

{
  "_id" : "870cf264-97b0-40fb-95fb-8c7759c74753",
  "createdAt" : "2018-02-06T09:16:40.876",
  "cartId" : "2c2f7803-59f4-49bf-9fa7-f00b0d09dce1",
  "currency" : "EUR",
  "taxModel" : "GROSS",
  "taxable" : false,
  "testOrder" : false,
  "productLineItems" : [ {
    "product" : {
      "sku" : "1018",
      "name" : "Decorative Sand (2 kg Jumbo Pack)",
      "essentialFeatures" : "Not suitable for children under the age of 8.",
      "shippingWeight" : 2000,
      "defaultImageDataUri" : "/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "_id" : "d7c4b63d-dd96-4a9b-86a7-2e96029b9e8c",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
          "templated" : true
        }
      }
    },
    "quantity" : {
      "value" : 5,
      "unit" : "PIECE"
    },
    "quantityInt" : 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" : "76a4e86a-9d88-49f4-b1e9-ef0a1822522e"
  }, {
    "product" : {
      "sku" : "1004",
      "name" : "White Sofa",
      "essentialFeatures" : null,
      "shippingWeight" : null,
      "defaultImageDataUri" : "/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "_id" : "5619d315-f050-4489-8dbd-a902ec62f57a",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
          "templated" : true
        }
      }
    },
    "quantity" : {
      "value" : 3,
      "unit" : "PIECE"
    },
    "quantityInt" : 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" : "cc775a9c-988f-4ccc-a29a-76d8bee3249d"
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "taxClass" : "REGULAR",
    "shippingMethod" : {
      "name" : "Standard Shipping",
      "description" : "Standard Shipping",
      "freeShippingValue" : {
        "currency" : "EUR",
        "amount" : 100
      },
      "fixedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 16.95
      },
      "weightBasedPrice" : null
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 2.7056
    } ]
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "taxClass" : "REGULAR",
    "paymentMethod" : {
      "name" : "PayPal",
      "description" : "Pay with 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
    } ]
  },
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 65.2287
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 9.1713
  },
  "initialSubtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "initialGrandTotal" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "initialBalanceDue" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "initialNetTotal" : {
    "currency" : "EUR",
    "amount" : 65.2287
  },
  "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" : "1st floor",
    "addressExtension" : "c/o Astrid Alster",
    "postalCode" : "20999",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a@example.com",
    "phone" : "(800) 555-0100",
    "mobile" : "(800) 555-0101",
    "doorCode" : "456",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "1st floor", "20999 Alsterwasser" ]
  },
  "billingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "1st floor",
    "addressExtension" : "c/o Astrid Alster",
    "postalCode" : "20999",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a@example.com",
    "phone" : "(800) 555-0100",
    "mobile" : "(800) 555-0101",
    "vatId" : "DE123456789",
    "taxNumber" : "HRE 987654/32123/864516",
    "birthDate" : "1985-05-11",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "1st floor", "20999 Alsterwasser" ]
  },
  "paymentStatus" : "PENDING",
  "shippingStatus" : "UNSHIPPED",
  "canceled" : false,
  "orderNumber" : "10001",
  "customerComment" : null,
  "orderNote" : "not paid yet",
  "entryDate" : "2018-02-06T09:16:40.876",
  "totalReceived" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "totalRefunded" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "openAmount" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "marketingChannel" : "Google shopping",
  "marketingSubchannel" : "Some category",
  "salesChannel" : "Storefront",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/870cf264-97b0-40fb-95fb-8c7759c74753"
    },
    "order" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/870cf264-97b0-40fb-95fb-8c7759c74753"
    },
    "order-note" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/870cf264-97b0-40fb-95fb-8c7759c74753/order-note"
    },
    "processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/870cf264-97b0-40fb-95fb-8c7759c74753/processes"
    },
    "events" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/870cf264-97b0-40fb-95fb-8c7759c74753/events"
    },
    "cancel" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/870cf264-97b0-40fb-95fb-8c7759c74753/cancel"
    },
    "order-receipt-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/order.receipt/uri.pdf"
    },
    "retry-create-invoice" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/870cf264-97b0-40fb-95fb-8c7759c74753/create-invoice"
    },
    "terms-and-conditions-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/some.pdf?hash=23213"
    },
    "right-of-withdrawal-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/some.pdf?hash=23213"
    }
  }
}

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/1642b56f-7ca3-449a-b90c-262f1256ab33/send-invoice' -i -X POST -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 9651

{
  "_id" : "1642b56f-7ca3-449a-b90c-262f1256ab33",
  "createdAt" : "2018-02-06T09:16:34.075",
  "cartId" : "da26fee2-14cd-45a7-8cbd-e5180b372058",
  "currency" : "EUR",
  "taxModel" : "GROSS",
  "taxable" : false,
  "testOrder" : false,
  "productLineItems" : [ {
    "product" : {
      "sku" : "1018",
      "name" : "Decorative Sand (2 kg Jumbo Pack)",
      "essentialFeatures" : "Not suitable for children under the age of 8.",
      "shippingWeight" : 2000,
      "defaultImageDataUri" : "/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "_id" : "f4e77c5a-bdb0-4560-816b-ab8c2c913008",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
          "templated" : true
        }
      }
    },
    "quantity" : {
      "value" : 5,
      "unit" : "PIECE"
    },
    "quantityInt" : 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" : "ac8ca536-b01c-4b42-994e-68176ee96c12"
  }, {
    "product" : {
      "sku" : "1004",
      "name" : "White Sofa",
      "essentialFeatures" : null,
      "shippingWeight" : null,
      "defaultImageDataUri" : "/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "_id" : "ad5f72a6-5a22-480e-881c-00f50d9f0595",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
          "templated" : true
        }
      }
    },
    "quantity" : {
      "value" : 3,
      "unit" : "PIECE"
    },
    "quantityInt" : 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" : "df27683f-5b81-40b1-a8e9-51cb852ce412"
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "taxClass" : "REGULAR",
    "shippingMethod" : {
      "name" : "Standard Shipping",
      "description" : "Standard Shipping",
      "freeShippingValue" : {
        "currency" : "EUR",
        "amount" : 100
      },
      "fixedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 16.95
      },
      "weightBasedPrice" : null
    },
    "lineItemTaxes" : [ {
      "taxClass" : "REGULAR",
      "taxRate" : 0.19,
      "currency" : "EUR",
      "amount" : 2.7056
    } ]
  },
  "paymentLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "taxClass" : "REGULAR",
    "paymentMethod" : {
      "name" : "PayPal",
      "description" : "Pay with 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
    } ]
  },
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "grandTotal" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "balanceDue" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "netTotal" : {
    "currency" : "EUR",
    "amount" : 65.2287
  },
  "taxTotal" : {
    "currency" : "EUR",
    "amount" : 9.1713
  },
  "initialSubtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "initialGrandTotal" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "initialBalanceDue" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "initialNetTotal" : {
    "currency" : "EUR",
    "amount" : 65.2287
  },
  "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" : "1st floor",
    "addressExtension" : "c/o Astrid Alster",
    "postalCode" : "20999",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a@example.com",
    "phone" : "(800) 555-0100",
    "mobile" : "(800) 555-0101",
    "doorCode" : "456",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "1st floor", "20999 Alsterwasser" ]
  },
  "billingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "1st floor",
    "addressExtension" : "c/o Astrid Alster",
    "postalCode" : "20999",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a@example.com",
    "phone" : "(800) 555-0100",
    "mobile" : "(800) 555-0101",
    "vatId" : "DE123456789",
    "taxNumber" : "HRE 987654/32123/864516",
    "birthDate" : "1985-05-11",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "1st floor", "20999 Alsterwasser" ]
  },
  "paymentStatus" : "PENDING",
  "shippingStatus" : "UNSHIPPED",
  "canceled" : false,
  "orderNumber" : "10001",
  "customerComment" : null,
  "orderNote" : "not paid yet",
  "entryDate" : "2018-02-06T09:16:34.075",
  "totalReceived" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "totalRefunded" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "openAmount" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "marketingChannel" : "Google shopping",
  "marketingSubchannel" : "Some category",
  "salesChannel" : "Storefront",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/1642b56f-7ca3-449a-b90c-262f1256ab33"
    },
    "order" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/1642b56f-7ca3-449a-b90c-262f1256ab33"
    },
    "order-note" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/1642b56f-7ca3-449a-b90c-262f1256ab33/order-note"
    },
    "processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/1642b56f-7ca3-449a-b90c-262f1256ab33/processes"
    },
    "events" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/1642b56f-7ca3-449a-b90c-262f1256ab33/events"
    },
    "cancel" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/1642b56f-7ca3-449a-b90c-262f1256ab33/cancel"
    },
    "order-receipt-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/order.receipt/uri.pdf"
    },
    "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/1642b56f-7ca3-449a-b90c-262f1256ab33/send-invoice"
    },
    "terms-and-conditions-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/some.pdf?hash=23213"
    },
    "right-of-withdrawal-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/some.pdf?hash=23213"
    }
  }
}

List order processes

A GET request will list all of the processes of an order.

Required scopes

ordp:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/b4c986c9-2dd0-43d7-acf8-bec928db0ad0/processes' -i -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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 5210

{
  "_embedded" : {
    "refund-processes" : [ {
      "amount" : {
        "currency" : "EUR",
        "amount" : 19.98
      },
      "status" : "VOIDED",
      "completed" : true,
      "_id" : "f11b2b23-3925-4359-bd41-51e9f74e0be3",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/b4c986c9-2dd0-43d7-acf8-bec928db0ad0/processes/refunds/f11b2b23-3925-4359-bd41-51e9f74e0be3"
        },
        "refund-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/b4c986c9-2dd0-43d7-acf8-bec928db0ad0/processes/refunds/f11b2b23-3925-4359-bd41-51e9f74e0be3"
        }
      }
    }, {
      "amount" : {
        "currency" : "EUR",
        "amount" : 39.96
      },
      "status" : "PENDING",
      "completed" : false,
      "_id" : "cc565c14-0dbe-454f-836e-10fbfbf13695",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/b4c986c9-2dd0-43d7-acf8-bec928db0ad0/processes/refunds/cc565c14-0dbe-454f-836e-10fbfbf13695"
        },
        "refund-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/b4c986c9-2dd0-43d7-acf8-bec928db0ad0/processes/refunds/cc565c14-0dbe-454f-836e-10fbfbf13695"
        },
        "mark-paid" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/b4c986c9-2dd0-43d7-acf8-bec928db0ad0/processes/refunds/cc565c14-0dbe-454f-836e-10fbfbf13695/mark-paid"
        }
      }
    } ],
    "cancel-processes" : [ {
      "lineItems" : [ {
        "productLineItemId" : "323fe1d3-a32a-4168-af14-1e997b6124aa",
        "quantity" : 2
      } ],
      "_id" : "c0b91077-4bbb-480e-876d-b90dc4d9d403",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/b4c986c9-2dd0-43d7-acf8-bec928db0ad0/processes/cancelations/c0b91077-4bbb-480e-876d-b90dc4d9d403"
        },
        "cancel-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/b4c986c9-2dd0-43d7-acf8-bec928db0ad0/processes/cancelations/c0b91077-4bbb-480e-876d-b90dc4d9d403"
        }
      }
    } ],
    "shipping-processes" : [ {
      "status" : "SHIPPED",
      "trackingCode" : "lookAtMyTrackingCodeWow",
      "trackingLink" : "http://tracking.is/fun?code=lookAtMyTrackingCodeWow",
      "lineItems" : [ {
        "productLineItemId" : "323fe1d3-a32a-4168-af14-1e997b6124aa",
        "quantity" : 3
      } ],
      "_id" : "7ab7a882-d96c-418f-89c2-6faa9bd1f025",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/b4c986c9-2dd0-43d7-acf8-bec928db0ad0/processes/shippings/7ab7a882-d96c-418f-89c2-6faa9bd1f025"
        },
        "shipping-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/b4c986c9-2dd0-43d7-acf8-bec928db0ad0/processes/shippings/7ab7a882-d96c-418f-89c2-6faa9bd1f025"
        },
        "mark-delivered" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/b4c986c9-2dd0-43d7-acf8-bec928db0ad0/processes/shippings/7ab7a882-d96c-418f-89c2-6faa9bd1f025/mark-delivered"
        }
      }
    } ],
    "payment-processes" : [ {
      "amount" : {
        "currency" : "EUR",
        "amount" : 74.4
      },
      "status" : "PAID",
      "completed" : true,
      "_id" : "75f47f49-faa9-4128-9271-813e10600313",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/b4c986c9-2dd0-43d7-acf8-bec928db0ad0/processes/payments/75f47f49-faa9-4128-9271-813e10600313"
        },
        "payment-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/b4c986c9-2dd0-43d7-acf8-bec928db0ad0/processes/payments/75f47f49-faa9-4128-9271-813e10600313"
        }
      }
    } ],
    "return-processes" : [ {
      "lineItems" : [ {
        "productLineItemId" : "323fe1d3-a32a-4168-af14-1e997b6124aa",
        "quantity" : 2,
        "status" : "RETURNED"
      } ],
      "_id" : "2c55a613-03a5-42d6-aaeb-2a2961b932cd",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/b4c986c9-2dd0-43d7-acf8-bec928db0ad0/processes/returns/2c55a613-03a5-42d6-aaeb-2a2961b932cd"
        },
        "return-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/b4c986c9-2dd0-43d7-acf8-bec928db0ad0/processes/returns/2c55a613-03a5-42d6-aaeb-2a2961b932cd"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/b4c986c9-2dd0-43d7-acf8-bec928db0ad0/processes"
    },
    "processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/b4c986c9-2dd0-43d7-acf8-bec928db0ad0/processes"
    },
    "payment-processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/b4c986c9-2dd0-43d7-acf8-bec928db0ad0/processes/payments"
    },
    "shipping-processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/b4c986c9-2dd0-43d7-acf8-bec928db0ad0/processes/shippings"
    },
    "return-processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/b4c986c9-2dd0-43d7-acf8-bec928db0ad0/processes/returns"
    },
    "cancel-processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/b4c986c9-2dd0-43d7-acf8-bec928db0ad0/processes/cancelations"
    },
    "refund-processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/b4c986c9-2dd0-43d7-acf8-bec928db0ad0/processes/refunds"
    }
  }
}

List payment processes

A GET request will list all of the payment processes of an order in a paged way.

Required scopes

pypr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/26fefcb7-d931-4043-a8e0-eeb6b95236a9/processes/payments?page=0&size=20' -i -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, PAID, VOIDED, FAILED or EXECUTED.

_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.

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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1563

{
  "_embedded" : {
    "payment-processes" : [ {
      "amount" : {
        "currency" : "EUR",
        "amount" : 74.4
      },
      "status" : "PENDING",
      "completed" : false,
      "_id" : "118d7028-5a7c-4ba2-86c5-f72b4641b5b2",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/26fefcb7-d931-4043-a8e0-eeb6b95236a9/processes/payments/118d7028-5a7c-4ba2-86c5-f72b4641b5b2"
        },
        "payment-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/26fefcb7-d931-4043-a8e0-eeb6b95236a9/processes/payments/118d7028-5a7c-4ba2-86c5-f72b4641b5b2"
        },
        "mark-voided" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/26fefcb7-d931-4043-a8e0-eeb6b95236a9/processes/payments/118d7028-5a7c-4ba2-86c5-f72b4641b5b2/mark-voided"
        },
        "mark-paid" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/26fefcb7-d931-4043-a8e0-eeb6b95236a9/processes/payments/118d7028-5a7c-4ba2-86c5-f72b4641b5b2/mark-paid"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/26fefcb7-d931-4043-a8e0-eeb6b95236a9/processes/payments?page=0&size=20"
    },
    "payment-processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/26fefcb7-d931-4043-a8e0-eeb6b95236a9/processes/payments"
    },
    "active" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/26fefcb7-d931-4043-a8e0-eeb6b95236a9/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/6a0515c0-00bc-408c-8557-1d9f791e32d8/processes/payments/12210854-14b0-48cd-8deb-de803b4c4a59' -i -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, PAID, VOIDED, FAILED or EXECUTED.

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.

_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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 883

{
  "amount" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "status" : "PENDING",
  "completed" : false,
  "_id" : "12210854-14b0-48cd-8deb-de803b4c4a59",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/6a0515c0-00bc-408c-8557-1d9f791e32d8/processes/payments/12210854-14b0-48cd-8deb-de803b4c4a59"
    },
    "payment-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/6a0515c0-00bc-408c-8557-1d9f791e32d8/processes/payments/12210854-14b0-48cd-8deb-de803b4c4a59"
    },
    "mark-voided" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/6a0515c0-00bc-408c-8557-1d9f791e32d8/processes/payments/12210854-14b0-48cd-8deb-de803b4c4a59/mark-voided"
    },
    "mark-paid" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/6a0515c0-00bc-408c-8557-1d9f791e32d8/processes/payments/12210854-14b0-48cd-8deb-de803b4c4a59/mark-paid"
    }
  }
}

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 info about request and response structure.

Required scopes

pypr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/d6cc25da-d2b7-4f61-b107-586a827a3b1c/processes/payments/active' -i -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 883

{
  "amount" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "status" : "PENDING",
  "completed" : false,
  "_id" : "2af572d6-d599-4147-937e-871844d653e4",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/d6cc25da-d2b7-4f61-b107-586a827a3b1c/processes/payments/2af572d6-d599-4147-937e-871844d653e4"
    },
    "payment-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/d6cc25da-d2b7-4f61-b107-586a827a3b1c/processes/payments/2af572d6-d599-4147-937e-871844d653e4"
    },
    "mark-voided" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/d6cc25da-d2b7-4f61-b107-586a827a3b1c/processes/payments/2af572d6-d599-4147-937e-871844d653e4/mark-voided"
    },
    "mark-paid" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/d6cc25da-d2b7-4f61-b107-586a827a3b1c/processes/payments/2af572d6-d599-4147-937e-871844d653e4/mark-paid"
    }
  }
}

Mark payment process as voided

A POST request will 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/d188c0c8-a086-4a3b-8ea9-d2ebdd4be311/processes/payments/817f355d-54b5-46d8-9c86-164a794358f9/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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 519

{
  "amount" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "status" : "VOIDED",
  "completed" : true,
  "_id" : "817f355d-54b5-46d8-9c86-164a794358f9",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/d188c0c8-a086-4a3b-8ea9-d2ebdd4be311/processes/payments/817f355d-54b5-46d8-9c86-164a794358f9"
    },
    "payment-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/d188c0c8-a086-4a3b-8ea9-d2ebdd4be311/processes/payments/817f355d-54b5-46d8-9c86-164a794358f9"
    }
  }
}

Mark payment process as paid

A POST request will 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/bb37cbc9-86fb-42c1-8492-9ce48ea66a11/processes/payments/9b1db772-a035-4043-924a-389d3d15a4cf/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" : 74.4
    }
  }
}'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 517

{
  "amount" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "status" : "PAID",
  "completed" : true,
  "_id" : "9b1db772-a035-4043-924a-389d3d15a4cf",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/bb37cbc9-86fb-42c1-8492-9ce48ea66a11/processes/payments/9b1db772-a035-4043-924a-389d3d15a4cf"
    },
    "payment-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/bb37cbc9-86fb-42c1-8492-9ce48ea66a11/processes/payments/9b1db772-a035-4043-924a-389d3d15a4cf"
    }
  }
}

List refund processes

A GET request will list all of the refund processes of an order in a paged way.

Required scopes

rfpr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/57366d2b-588c-4013-b695-2ce027a7336d/processes/refunds?page=0&size=20' -i -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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
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" : "2da164f7-ec1b-49b8-b659-25717bd8ca57",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/57366d2b-588c-4013-b695-2ce027a7336d/processes/refunds/2da164f7-ec1b-49b8-b659-25717bd8ca57"
        },
        "refund-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/57366d2b-588c-4013-b695-2ce027a7336d/processes/refunds/2da164f7-ec1b-49b8-b659-25717bd8ca57"
        },
        "mark-paid" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/57366d2b-588c-4013-b695-2ce027a7336d/processes/refunds/2da164f7-ec1b-49b8-b659-25717bd8ca57/mark-paid"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/57366d2b-588c-4013-b695-2ce027a7336d/processes/refunds?page=0&size=20"
    },
    "refund-processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/57366d2b-588c-4013-b695-2ce027a7336d/processes/refunds"
    },
    "active" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/57366d2b-588c-4013-b695-2ce027a7336d/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/42371108-af71-4759-b571-05e85f25a25e/processes/refunds/e329f318-ba91-4c30-8840-62f64756efe6' -i -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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 697

{
  "amount" : {
    "currency" : "EUR",
    "amount" : 19.98
  },
  "status" : "PENDING",
  "completed" : false,
  "_id" : "e329f318-ba91-4c30-8840-62f64756efe6",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/42371108-af71-4759-b571-05e85f25a25e/processes/refunds/e329f318-ba91-4c30-8840-62f64756efe6"
    },
    "refund-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/42371108-af71-4759-b571-05e85f25a25e/processes/refunds/e329f318-ba91-4c30-8840-62f64756efe6"
    },
    "mark-paid" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/42371108-af71-4759-b571-05e85f25a25e/processes/refunds/e329f318-ba91-4c30-8840-62f64756efe6/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 info about request and response structure.

Required scopes

rfpr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/137ac52f-f7a4-429a-82dc-6e2f76e6bf0f/processes/refunds/active' -i -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 697

{
  "amount" : {
    "currency" : "EUR",
    "amount" : 19.98
  },
  "status" : "PENDING",
  "completed" : false,
  "_id" : "05465b98-761a-4465-b94d-e4f064a916c6",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/137ac52f-f7a4-429a-82dc-6e2f76e6bf0f/processes/refunds/05465b98-761a-4465-b94d-e4f064a916c6"
    },
    "refund-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/137ac52f-f7a4-429a-82dc-6e2f76e6bf0f/processes/refunds/05465b98-761a-4465-b94d-e4f064a916c6"
    },
    "mark-paid" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/137ac52f-f7a4-429a-82dc-6e2f76e6bf0f/processes/refunds/05465b98-761a-4465-b94d-e4f064a916c6/mark-paid"
    }
  }
}

Mark refund process as paid

A POST request will 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 paid.

details.amount.currency

String

The currency of the amount paid.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/78f61e03-f574-4db2-8e14-e26eec475254/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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 515

{
  "amount" : {
    "currency" : "EUR",
    "amount" : 19.98
  },
  "status" : "PAID",
  "completed" : true,
  "_id" : "550c33b7-b6de-4c81-a585-a9dbc13d771d",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/78f61e03-f574-4db2-8e14-e26eec475254/processes/refunds/550c33b7-b6de-4c81-a585-a9dbc13d771d"
    },
    "refund-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/78f61e03-f574-4db2-8e14-e26eec475254/processes/refunds/550c33b7-b6de-4c81-a585-a9dbc13d771d"
    }
  }
}

List shipping processes

A GET request will list all of the shipping processes of an order in a paged way.

Required scopes

shpr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/9aca0ded-d63d-4d4a-b86e-49b1bbc7b18e/processes/shippings?page=0&size=20' -i -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 {{values}}.

_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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1597

{
  "_embedded" : {
    "shipping-processes" : [ {
      "status" : "PENDING",
      "trackingCode" : "lookAtMyTrackingCodeWow",
      "trackingLink" : "http://tracking.is/fun?code=lookAtMyTrackingCodeWow",
      "lineItems" : [ {
        "productLineItemId" : "86ce0ce3-1304-4d00-a26b-9cad84d131d8",
        "quantity" : 3
      } ],
      "_id" : "e5665803-38b8-40c7-bb75-db419425d106",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/9aca0ded-d63d-4d4a-b86e-49b1bbc7b18e/processes/shippings/e5665803-38b8-40c7-bb75-db419425d106"
        },
        "shipping-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/9aca0ded-d63d-4d4a-b86e-49b1bbc7b18e/processes/shippings/e5665803-38b8-40c7-bb75-db419425d106"
        },
        "mark-shipped" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/9aca0ded-d63d-4d4a-b86e-49b1bbc7b18e/processes/shippings/e5665803-38b8-40c7-bb75-db419425d106/mark-shipped"
        },
        "mark-delivered" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/9aca0ded-d63d-4d4a-b86e-49b1bbc7b18e/processes/shippings/e5665803-38b8-40c7-bb75-db419425d106/mark-delivered"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/9aca0ded-d63d-4d4a-b86e-49b1bbc7b18e/processes/shippings?page=0&size=20"
    },
    "shipping-processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/9aca0ded-d63d-4d4a-b86e-49b1bbc7b18e/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/f7e3f59a-e31e-4b77-b0fa-ca3c3b944f78/processes/shippings/c6075949-e71a-4d7d-b4f2-f7d0d4d5ab7b' -i -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 {{values}}.

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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1045

{
  "status" : "PENDING",
  "trackingCode" : "lookAtMyTrackingCodeWow",
  "trackingLink" : "http://tracking.is/fun?code=lookAtMyTrackingCodeWow",
  "lineItems" : [ {
    "productLineItemId" : "e8e52faa-2ed4-4d74-9113-95174567737b",
    "quantity" : 3
  } ],
  "_id" : "c6075949-e71a-4d7d-b4f2-f7d0d4d5ab7b",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/f7e3f59a-e31e-4b77-b0fa-ca3c3b944f78/processes/shippings/c6075949-e71a-4d7d-b4f2-f7d0d4d5ab7b"
    },
    "shipping-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/f7e3f59a-e31e-4b77-b0fa-ca3c3b944f78/processes/shippings/c6075949-e71a-4d7d-b4f2-f7d0d4d5ab7b"
    },
    "mark-shipped" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/f7e3f59a-e31e-4b77-b0fa-ca3c3b944f78/processes/shippings/c6075949-e71a-4d7d-b4f2-f7d0d4d5ab7b/mark-shipped"
    },
    "mark-delivered" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/f7e3f59a-e31e-4b77-b0fa-ca3c3b944f78/processes/shippings/c6075949-e71a-4d7d-b4f2-f7d0d4d5ab7b/mark-delivered"
    }
  }
}

Create shipping processes

A POST request will 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 a mail is to be sent out with this shipping process transition.

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/e2014bf5-1bf6-406c-a684-0b397828dd3f/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,
  "trackingCode" : "lookAtMyTrackingCodeWow",
  "trackingLink" : "http://tracking.is/fun?code=lookAtMyTrackingCodeWow",
  "lineItems" : [ {
    "quantity" : 3,
    "productLineItemId" : "39ea5c11-e7e3-4fd6-a5be-fbce3ee02c20"
  } ]
}'

Example response

HTTP/1.1 201 Created
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Location: https://api-shop.beyondshop.cloud/api/orders/e2014bf5-1bf6-406c-a684-0b397828dd3f/processes/shippings/529bb7f9-ff20-4af3-a324-db2d676fd704
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1045

{
  "status" : "PENDING",
  "trackingCode" : "lookAtMyTrackingCodeWow",
  "trackingLink" : "http://tracking.is/fun?code=lookAtMyTrackingCodeWow",
  "lineItems" : [ {
    "productLineItemId" : "39ea5c11-e7e3-4fd6-a5be-fbce3ee02c20",
    "quantity" : 3
  } ],
  "_id" : "529bb7f9-ff20-4af3-a324-db2d676fd704",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/e2014bf5-1bf6-406c-a684-0b397828dd3f/processes/shippings/529bb7f9-ff20-4af3-a324-db2d676fd704"
    },
    "shipping-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/e2014bf5-1bf6-406c-a684-0b397828dd3f/processes/shippings/529bb7f9-ff20-4af3-a324-db2d676fd704"
    },
    "mark-shipped" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/e2014bf5-1bf6-406c-a684-0b397828dd3f/processes/shippings/529bb7f9-ff20-4af3-a324-db2d676fd704/mark-shipped"
    },
    "mark-delivered" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/e2014bf5-1bf6-406c-a684-0b397828dd3f/processes/shippings/529bb7f9-ff20-4af3-a324-db2d676fd704/mark-delivered"
    }
  }
}

Mark shipment as shipped

A POST request will mark the shipment as shipped.

Required scopes

shpr:u

Request body properties

Path Type Description

comment

String

The comment to this status change.

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/8834df10-e3ba-4540-a115-d00eaae33854/processes/shippings/ed0af357-7550-4c9c-ada0-e84f9d15b2cc/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!",
  "details" : {
    "trackingCode" : "lookAtMyTrackingCodeWow",
    "trackingLink" : "http://tracking.is/fun?code=lookAtMyTrackingCodeWow"
  }
}'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 859

{
  "status" : "SHIPPED",
  "trackingCode" : "lookAtMyTrackingCodeWow",
  "trackingLink" : "http://tracking.is/fun?code=lookAtMyTrackingCodeWow",
  "lineItems" : [ {
    "productLineItemId" : "10352ba5-2915-4115-a07c-e6628e699705",
    "quantity" : 3
  } ],
  "_id" : "ed0af357-7550-4c9c-ada0-e84f9d15b2cc",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/8834df10-e3ba-4540-a115-d00eaae33854/processes/shippings/ed0af357-7550-4c9c-ada0-e84f9d15b2cc"
    },
    "shipping-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/8834df10-e3ba-4540-a115-d00eaae33854/processes/shippings/ed0af357-7550-4c9c-ada0-e84f9d15b2cc"
    },
    "mark-delivered" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/8834df10-e3ba-4540-a115-d00eaae33854/processes/shippings/ed0af357-7550-4c9c-ada0-e84f9d15b2cc/mark-delivered"
    }
  }
}

Mark shipment as delivered

A POST request will 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/4a2b6b55-a82b-468e-9036-5f633702f9ca/processes/shippings/5f27a9a1-8ead-44fe-b8e0-8e77ef4cc365/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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 671

{
  "status" : "DELIVERED",
  "trackingCode" : "lookAtMyTrackingCodeWow",
  "trackingLink" : "http://tracking.is/fun?code=lookAtMyTrackingCodeWow",
  "lineItems" : [ {
    "productLineItemId" : "ed09f096-f8ef-4fa9-b080-3c7fd00c8c33",
    "quantity" : 3
  } ],
  "_id" : "5f27a9a1-8ead-44fe-b8e0-8e77ef4cc365",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/4a2b6b55-a82b-468e-9036-5f633702f9ca/processes/shippings/5f27a9a1-8ead-44fe-b8e0-8e77ef4cc365"
    },
    "shipping-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/4a2b6b55-a82b-468e-9036-5f633702f9ca/processes/shippings/5f27a9a1-8ead-44fe-b8e0-8e77ef4cc365"
    }
  }
}

List return processes

A GET request will 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/9e284c21-5d6e-49b3-881c-1d95a8946f10/processes/returns?page=0&size=20' -i -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.

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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1058

{
  "_embedded" : {
    "return-processes" : [ {
      "lineItems" : [ {
        "productLineItemId" : "506275c4-ee27-426f-9e7e-e096817523cb",
        "quantity" : 3,
        "status" : "RETURNED"
      } ],
      "_id" : "7b3776a5-5714-49fd-9ac5-fd3b9213bd2e",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/9e284c21-5d6e-49b3-881c-1d95a8946f10/processes/returns/7b3776a5-5714-49fd-9ac5-fd3b9213bd2e"
        },
        "return-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/9e284c21-5d6e-49b3-881c-1d95a8946f10/processes/returns/7b3776a5-5714-49fd-9ac5-fd3b9213bd2e"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/9e284c21-5d6e-49b3-881c-1d95a8946f10/processes/returns?page=0&size=20"
    },
    "return-processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/9e284c21-5d6e-49b3-881c-1d95a8946f10/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/42e54c45-a94e-4186-bc37-bb44dd69c2cb/processes/returns/3e2395da-84ae-4a54-84b7-85edc9a710d8' -i -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.

_links

Object

See Hypermedia

Links

Relation Description

return-process

The link to the current return process.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 546

{
  "lineItems" : [ {
    "productLineItemId" : "4eacdb82-132a-4928-b358-695db635fd62",
    "quantity" : 3,
    "status" : "RETURNED"
  } ],
  "_id" : "3e2395da-84ae-4a54-84b7-85edc9a710d8",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/42e54c45-a94e-4186-bc37-bb44dd69c2cb/processes/returns/3e2395da-84ae-4a54-84b7-85edc9a710d8"
    },
    "return-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/42e54c45-a94e-4186-bc37-bb44dd69c2cb/processes/returns/3e2395da-84ae-4a54-84b7-85edc9a710d8"
    }
  }
}

Create return processes

A POST request will create a new return processes for an order.

Required scopes

rtpr: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 return process.

lineItems[].quantity

Number

The quantity of the product line item in this return process.

lineItems[].status

String

The status of the product line item in this return process.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/c3f2e563-5777-44b1-8040-2e57a6f08200/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!",
  "lineItems" : [ {
    "quantity" : 3,
    "productLineItemId" : "5326664a-d464-423b-8f92-5cbf92ff17b1",
    "status" : "RETURNED"
  } ]
}'

Example response

HTTP/1.1 201 Created
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Location: https://api-shop.beyondshop.cloud/api/orders/c3f2e563-5777-44b1-8040-2e57a6f08200/processes/returns/35a35c66-9711-486b-a61f-e1cd5a03d81b
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 546

{
  "lineItems" : [ {
    "productLineItemId" : "5326664a-d464-423b-8f92-5cbf92ff17b1",
    "quantity" : 3,
    "status" : "RETURNED"
  } ],
  "_id" : "35a35c66-9711-486b-a61f-e1cd5a03d81b",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/c3f2e563-5777-44b1-8040-2e57a6f08200/processes/returns/35a35c66-9711-486b-a61f-e1cd5a03d81b"
    },
    "return-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/c3f2e563-5777-44b1-8040-2e57a6f08200/processes/returns/35a35c66-9711-486b-a61f-e1cd5a03d81b"
    }
  }
}

List cancelation processes

A GET request will 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/ef141b7e-fcad-4dcc-8f01-1bc86c29dfe7/processes/cancelations?page=0&size=20' -i -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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1047

{
  "_embedded" : {
    "cancel-processes" : [ {
      "lineItems" : [ {
        "productLineItemId" : "8c8bdac0-9fae-46d7-8cbf-4d1db7f25b7c",
        "quantity" : 3
      } ],
      "_id" : "aab14756-fd3a-4a3c-8017-4ab6a2679746",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/ef141b7e-fcad-4dcc-8f01-1bc86c29dfe7/processes/cancelations/aab14756-fd3a-4a3c-8017-4ab6a2679746"
        },
        "cancel-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/ef141b7e-fcad-4dcc-8f01-1bc86c29dfe7/processes/cancelations/aab14756-fd3a-4a3c-8017-4ab6a2679746"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/ef141b7e-fcad-4dcc-8f01-1bc86c29dfe7/processes/cancelations?page=0&size=20"
    },
    "cancel-processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/ef141b7e-fcad-4dcc-8f01-1bc86c29dfe7/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.

Required scopes

clpr:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/4e7ea9e1-8dfa-468c-ab04-19f21f09fced/processes/cancelations/73dfd314-3936-47f1-8deb-113a26b07417' -i -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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 529

{
  "lineItems" : [ {
    "productLineItemId" : "a3206a84-11b8-4ff9-8ba1-65b7f2e7555a",
    "quantity" : 3
  } ],
  "_id" : "73dfd314-3936-47f1-8deb-113a26b07417",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/4e7ea9e1-8dfa-468c-ab04-19f21f09fced/processes/cancelations/73dfd314-3936-47f1-8deb-113a26b07417"
    },
    "cancel-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/4e7ea9e1-8dfa-468c-ab04-19f21f09fced/processes/cancelations/73dfd314-3936-47f1-8deb-113a26b07417"
    }
  }
}

Create cancelation processes

A POST request will create a new cancelation process for an order.

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/98376d70-7ffc-4e14-ac19-256c9a03f2da/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" : "da71e8f9-ea54-4c1f-a591-49e59668b245"
  } ]
}'

Example response

HTTP/1.1 201 Created
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Location: https://api-shop.beyondshop.cloud/api/orders/98376d70-7ffc-4e14-ac19-256c9a03f2da/processes/cancelations/a7df07b4-50de-4880-b5e2-904fa3ed35b7
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 529

{
  "lineItems" : [ {
    "productLineItemId" : "da71e8f9-ea54-4c1f-a591-49e59668b245",
    "quantity" : 3
  } ],
  "_id" : "a7df07b4-50de-4880-b5e2-904fa3ed35b7",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/98376d70-7ffc-4e14-ac19-256c9a03f2da/processes/cancelations/a7df07b4-50de-4880-b5e2-904fa3ed35b7"
    },
    "cancel-process" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/98376d70-7ffc-4e14-ac19-256c9a03f2da/processes/cancelations/a7df07b4-50de-4880-b5e2-904fa3ed35b7"
    }
  }
}

Cancel order

A POST request will 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/cb4fc7a8-e86e-463f-974f-96d925e03921/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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 9339

{
  "_id" : "cb4fc7a8-e86e-463f-974f-96d925e03921",
  "createdAt" : "2018-02-06T09:16:07.553",
  "cartId" : "bc290d9b-89d5-45db-8c30-27b583a2db76",
  "currency" : "EUR",
  "taxModel" : "GROSS",
  "taxable" : true,
  "testOrder" : false,
  "productLineItems" : [ {
    "product" : {
      "sku" : "1004",
      "name" : "White Sofa",
      "essentialFeatures" : null,
      "shippingWeight" : null,
      "defaultImageDataUri" : "/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "_id" : "bc9d4ca5-ea96-4678-9158-07a78315dc87",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
          "templated" : true
        }
      }
    },
    "quantity" : {
      "value" : 0,
      "unit" : "PIECE"
    },
    "quantityInt" : 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" : "5f77828d-1b03-4148-bf38-fe009fe0c0ad"
  }, {
    "product" : {
      "sku" : "1018",
      "name" : "Decorative Sand (2 kg Jumbo Pack)",
      "essentialFeatures" : "Not suitable for children under the age of 8.",
      "shippingWeight" : 2000,
      "defaultImageDataUri" : "/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "_id" : "21ace70b-df42-40cd-a35f-9388dbdead02",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
          "templated" : true
        }
      }
    },
    "quantity" : {
      "value" : 0,
      "unit" : "PIECE"
    },
    "quantityInt" : 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
      }
    },
    "_id" : "ee1a1400-90e7-4572-85fe-220dfc9789b3"
  } ],
  "shippingLineItem" : {
    "lineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 0
    },
    "initialLineItemPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "taxClass" : "REGULAR",
    "shippingMethod" : {
      "name" : "Standard Shipping",
      "description" : "Standard Shipping",
      "freeShippingValue" : {
        "currency" : "EUR",
        "amount" : 100
      },
      "fixedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 16.95
      },
      "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" : {
      "name" : "PayPal",
      "description" : "Pay with 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
    } ]
  },
  "subtotal" : {
    "currency" : "EUR",
    "amount" : 57.45
  },
  "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" : 74.4
  },
  "initialBalanceDue" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "initialNetTotal" : {
    "currency" : "EUR",
    "amount" : 65.2287
  },
  "initialTaxTotal" : {
    "currency" : "EUR",
    "amount" : 9.1713
  },
  "taxes" : [ {
    "taxClass" : "REGULAR",
    "taxRate" : 0.0,
    "currency" : "EUR",
    "amount" : 0
  } ],
  "shippingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "1st floor",
    "addressExtension" : "c/o Astrid Alster",
    "postalCode" : "20999",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a@example.com",
    "phone" : "(800) 555-0100",
    "mobile" : "(800) 555-0101",
    "doorCode" : "456",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "1st floor", "20999 Alsterwasser" ]
  },
  "billingAddress" : {
    "salutation" : "Mrs",
    "gender" : "FEMALE",
    "company" : "Astrid Alster GmbH",
    "title" : null,
    "firstName" : "Astrid",
    "middleName" : "Agnes",
    "lastName" : "Alster",
    "street" : "Alsterwasserweg",
    "houseNumber" : "2",
    "street2" : "1st floor",
    "addressExtension" : "c/o Astrid Alster",
    "postalCode" : "20999",
    "city" : "Alsterwasser",
    "country" : "DE",
    "state" : "Hamburg",
    "email" : "a@example.com",
    "phone" : "(800) 555-0100",
    "mobile" : "(800) 555-0101",
    "vatId" : "DE123456789",
    "taxNumber" : "HRE 987654/32123/864516",
    "birthDate" : "1985-05-11",
    "displayAddressLines" : [ "Astrid Alster GmbH", "Astrid Agnes Alster", "Alsterwasserweg 2", "1st floor", "20999 Alsterwasser" ]
  },
  "paymentStatus" : "REFUND_PENDING",
  "shippingStatus" : "SHIPPED",
  "canceled" : true,
  "orderNumber" : "10001",
  "customerComment" : null,
  "orderNote" : "not paid yet",
  "entryDate" : "2018-02-06T09:16:07.553",
  "totalReceived" : {
    "currency" : "EUR",
    "amount" : 74.4
  },
  "totalRefunded" : {
    "currency" : "EUR",
    "amount" : 0
  },
  "openAmount" : {
    "currency" : "EUR",
    "amount" : -74.4
  },
  "marketingChannel" : "Google shopping",
  "marketingSubchannel" : "Some category",
  "salesChannel" : "Storefront",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/cb4fc7a8-e86e-463f-974f-96d925e03921"
    },
    "order" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/cb4fc7a8-e86e-463f-974f-96d925e03921"
    },
    "order-note" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/cb4fc7a8-e86e-463f-974f-96d925e03921/order-note"
    },
    "processes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/cb4fc7a8-e86e-463f-974f-96d925e03921/processes"
    },
    "events" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/cb4fc7a8-e86e-463f-974f-96d925e03921/events"
    },
    "order-receipt-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/order.receipt/uri.pdf"
    },
    "create-invoice" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/cb4fc7a8-e86e-463f-974f-96d925e03921/create-invoice"
    },
    "right-of-withdrawal-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/some.pdf?hash=23213"
    },
    "terms-and-conditions-pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/pdf-storage/attachments/some.pdf?hash=23213"
    }
  }
}

List order events

A GET request will list all events of an order in a paged way.

Required scopes

orde:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/orders/99fee07f-7bbc-4e9d-93c1-b6506fc528fb/events' -i -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_embedded.order-events[].triggeredBy

Varies

The user or client that triggered the order event.

_embedded.order-events[].comment

Varies

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-paid, payment-executed, payment-failed, payment-execution-temporarily-failed, invoice-created, invoice-sent, order-shipping-address-changed, order-billing-address-changed, shipping-shipped, shipping-delivered, shipping-pending, refund-created, refund-voided or refund-paid.

_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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2052

{
  "_embedded" : {
    "order-events" : [ {
      "triggeredBy" : "user",
      "comment" : "comment",
      "createdAt" : "2018-02-06T09:14:52.066",
      "details" : {
        "paymentProcessId" : "b206bda4-2c15-4dc4-8143-051fbebd586d",
        "type" : "payment-voided"
      },
      "_links" : {
        "payment-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/99fee07f-7bbc-4e9d-93c1-b6506fc528fb/processes/payments/b206bda4-2c15-4dc4-8143-051fbebd586d"
        }
      }
    }, {
      "triggeredBy" : null,
      "comment" : null,
      "createdAt" : "2018-02-06T09:14:51.911",
      "details" : {
        "amount" : {
          "currency" : "EUR",
          "amount" : 0
        },
        "paymentProcessId" : null,
        "type" : "payment-created"
      }
    }, {
      "triggeredBy" : "user",
      "comment" : "customer transfer",
      "createdAt" : "2018-02-06T09:14:51.669",
      "details" : {
        "amount" : {
          "currency" : "EUR",
          "amount" : 74.4
        },
        "paymentProcessId" : "3e0cd3a4-72c3-4445-9cde-e0dfdd4a232f",
        "type" : "payment-paid"
      },
      "_links" : {
        "payment-process" : {
          "href" : "https://api-shop.beyondshop.cloud/api/orders/99fee07f-7bbc-4e9d-93c1-b6506fc528fb/processes/payments/3e0cd3a4-72c3-4445-9cde-e0dfdd4a232f"
        }
      }
    }, {
      "triggeredBy" : null,
      "comment" : null,
      "createdAt" : "2018-02-06T09:14:51.319",
      "details" : {
        "amount" : {
          "currency" : "EUR",
          "amount" : 74.4
        },
        "paymentProcessId" : null,
        "type" : "payment-created"
      }
    }, {
      "triggeredBy" : null,
      "comment" : null,
      "createdAt" : "2018-02-06T09:14:51.135",
      "details" : {
        "type" : "order-created"
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/orders/99fee07f-7bbc-4e9d-93c1-b6506fc528fb/events"
    }
  },
  "page" : {
    "size" : 10,
    "totalElements" : 5,
    "totalPages" : 1,
    "number" : 0
  }
}

Payment Methods

The payment-methods resources is used to get information about payment methods of this shop.

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/cb19ca4a-817c-406a-80b1-562d5911867a' -i -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 administration 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 mininmum 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.

activatable

Boolean

Indicates if a payment method can be activated (feature enabled for the shop). 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).

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Last-Modified: Tue, 06 Feb 2018 09:07:36 GMT
ETag: "3"
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1572

{
  "name" : "PayPal",
  "description" : "Pay with PayPal",
  "officialName" : "PayPal",
  "officialDescription" : "Pay with PayPal",
  "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,
  "activatable" : true,
  "_id" : "cb19ca4a-817c-406a-80b1-562d5911867a",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/cb19ca4a-817c-406a-80b1-562d5911867a"
    },
    "payment-method" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/cb19ca4a-817c-406a-80b1-562d5911867a"
    },
    "logo-tile" : {
      "href" : "http://tile-logo.com"
    },
    "logo-details" : {
      "href" : "http://details-logo.com"
    },
    "logo-storefront" : {
      "href" : "http://storefront-logo.com"
    },
    "logo-list" : {
      "href" : "http://list-logo.com"
    },
    "integration-status" : {
      "href" : "https://api-shop.beyondshop.cloud/api/paypal/merchant-account-status"
    },
    "deactivate-payment-method" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/cb19ca4a-817c-406a-80b1-562d5911867a/deactivate"
    },
    "payment-integration" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/cb19ca4a-817c-406a-80b1-562d5911867a/payment-integration"
    }
  }
}

List payment methods

A GET request will list all of the payment methods in a paged manner.

Required scopes

pymt:r

Example request

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

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 3045

{
  "_embedded" : {
    "payment-methods" : [ {
      "name" : "PayPal",
      "description" : "Pay with PayPal",
      "officialName" : "PayPal",
      "officialDescription" : "Pay with PayPal",
      "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,
      "activatable" : true,
      "_id" : "e5f44d46-3907-405d-8e78-b22c035a81a9",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/e5f44d46-3907-405d-8e78-b22c035a81a9"
        },
        "payment-method" : {
          "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/e5f44d46-3907-405d-8e78-b22c035a81a9"
        },
        "deactivate-payment-method" : {
          "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/e5f44d46-3907-405d-8e78-b22c035a81a9/deactivate"
        },
        "payment-integration" : {
          "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/e5f44d46-3907-405d-8e78-b22c035a81a9/payment-integration"
        }
      }
    }, {
      "name" : "Credit Card",
      "description" : "Pay with CreditCard",
      "officialName" : "Credit Card",
      "officialDescription" : "Pay with CreditCard",
      "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,
      "activatable" : true,
      "_id" : "8da5dc61-491c-4567-8802-e29cc2776b82",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/8da5dc61-491c-4567-8802-e29cc2776b82"
        },
        "payment-method" : {
          "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/8da5dc61-491c-4567-8802-e29cc2776b82"
        },
        "activate-payment-method" : {
          "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/8da5dc61-491c-4567-8802-e29cc2776b82/activate"
        },
        "payment-integration" : {
          "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/8da5dc61-491c-4567-8802-e29cc2776b82/payment-integration"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods{?page,size,sort}",
      "templated" : true
    },
    "profile" : {
      "href" : "https://api-shop.beyondshop.cloud/api/profile/payment-methods"
    },
    "search" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/search"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

Create payment method

A POST request is used to create a payment method.

Required scopes

pymt:c

Request body properties

Path Type Description Constraints

officialName

String

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

Must not be empty

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.

Must not be empty

description

String

Description of the payment method that is used during checkout.

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 mininmum value of the cart so that this payment method can be used.

position

Number

The sorting position of the payment method in the merchant administration in relation to other payment methods.

taxClass

String

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

Must not be null

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/payment-methods' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <Access token>' -d '{
  "name" : "A Payment Method",
  "description" : "Description of A Payment Method",
  "officialName" : "Official Name",
  "officialDescription" : "Official description of method",
  "taxClass" : "REGULAR",
  "discountOrFee" : {
    "type" : "ABSOLUTE",
    "absoluteValue" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 12.34
    }
  },
  "position" : 0,
  "serviceableCountries" : [ "DE", "GB" ],
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 19.99
  }
}'

Example response

HTTP/1.1 201 Created
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
ETag: "1"
Last-Modified: Tue, 06 Feb 2018 09:07:43 GMT
Location: https://api-shop.beyondshop.cloud/api/payment-methods/645ea804-9995-407c-9551-54de3a2dc96e
Content-Type: application/json;charset=UTF-8
Content-Length: 1244

{
  "name" : "A Payment Method",
  "description" : "Description of A Payment Method",
  "officialName" : "Official Name",
  "officialDescription" : "Official description of method",
  "taxClass" : "REGULAR",
  "discountOrFee" : {
    "type" : "ABSOLUTE",
    "absoluteValue" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 12.34
    },
    "percentageValue" : null
  },
  "position" : 1,
  "serviceableCountries" : [ "DE", "GB" ],
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 19.99
  },
  "activated" : false,
  "activeLogoSet" : null,
  "onlinePayment" : false,
  "activatable" : true,
  "_id" : "645ea804-9995-407c-9551-54de3a2dc96e",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/645ea804-9995-407c-9551-54de3a2dc96e"
    },
    "payment-method" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/645ea804-9995-407c-9551-54de3a2dc96e"
    },
    "activate-payment-method" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/645ea804-9995-407c-9551-54de3a2dc96e/activate"
    },
    "payment-integration" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/645ea804-9995-407c-9551-54de3a2dc96e/payment-integration"
    }
  }
}

Update payment method

A PUT request is used to update a payment method.

Required scopes

pymt:u

Request body properties

Path Type Description Constraints

officialName

String

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

Must not be empty

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.

Must not be empty

description

String

Description of the payment method that is used during checkout.

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 mininmum value of the cart so that this payment method can be used.

position

Number

The sorting position of the payment method in the merchant administration in relation to other payment methods.

taxClass

String

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

Must not be null

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/payment-methods/f600e997-0904-40d9-b2d2-1d51f16c30d3' -i -X PUT -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>' -d '{
  "name" : "Another name",
  "description" : "Pay with PayPal",
  "officialName" : "PayPal",
  "officialDescription" : "Pay with PayPal",
  "taxClass" : "REGULAR",
  "discountOrFee" : {
    "type" : "ABSOLUTE",
    "absoluteValue" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 2.0
    }
  },
  "position" : 0,
  "serviceableCountries" : [ "DE" ],
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 10.0
  }
}'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
ETag: "1"
Last-Modified: Tue, 06 Feb 2018 09:07:40 GMT
Location: https://api-shop.beyondshop.cloud/api/payment-methods/f600e997-0904-40d9-b2d2-1d51f16c30d3
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1192

{
  "name" : "Another name",
  "description" : "Pay with PayPal",
  "officialName" : "PayPal",
  "officialDescription" : "Pay with PayPal",
  "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,
  "activatable" : true,
  "_id" : "f600e997-0904-40d9-b2d2-1d51f16c30d3",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/f600e997-0904-40d9-b2d2-1d51f16c30d3"
    },
    "payment-method" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/f600e997-0904-40d9-b2d2-1d51f16c30d3"
    },
    "deactivate-payment-method" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/f600e997-0904-40d9-b2d2-1d51f16c30d3/deactivate"
    },
    "payment-integration" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/f600e997-0904-40d9-b2d2-1d51f16c30d3/payment-integration"
    }
  }
}

Delete payment method

A DELETE request is used to delete a payment method.

Required scopes

pymt:d

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/payment-methods/e3bc12ae-06f5-45e7-b12b-7534b19d05fb' -i -X DELETE -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

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/c0ab59b6-5945-4b9d-b207-ca1de0a1ea20
https://api-shop.beyondshop.cloud/api/payment-methods/b148c613-985c-4730-b825-4facb0cc60b7
https://api-shop.beyondshop.cloud/api/payment-methods/03ce096e-f327-47ca-9408-0f17e65c3166
https://api-shop.beyondshop.cloud/api/payment-methods/dfa06feb-8ab4-46bb-8449-ff534f82ac3f'

Example response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
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/d07f357f-5fd1-4957-96b2-0b3272a498a9/activate' -i -X POST -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 968

{
  "name" : "A Payment Method",
  "description" : "Description of A Payment Method",
  "officialName" : "Official Name",
  "officialDescription" : "Official description of method",
  "taxClass" : "REGULAR",
  "discountOrFee" : {
    "type" : "ABSOLUTE",
    "absoluteValue" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 12.34
    },
    "percentageValue" : null
  },
  "position" : 1,
  "serviceableCountries" : [ "DE", "GB" ],
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 19.99
  },
  "activated" : true,
  "activeLogoSet" : null,
  "onlinePayment" : false,
  "activatable" : true,
  "_id" : "d07f357f-5fd1-4957-96b2-0b3272a498a9",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/d07f357f-5fd1-4957-96b2-0b3272a498a9"
    },
    "deactivate-payment-method" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/d07f357f-5fd1-4957-96b2-0b3272a498a9/deactivate"
    }
  }
}

Dectivate a payment method

Required scopes

pymt:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/payment-methods/19fa0fd2-1b4d-474c-86fe-ea844ed0795e/deactivate' -i -X POST -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 983

{
  "name" : "The second Payment Method",
  "description" : "Description of The second Payment Method",
  "officialName" : "Official Name",
  "officialDescription" : "Official description of method",
  "taxClass" : "REGULAR",
  "discountOrFee" : {
    "type" : "ABSOLUTE",
    "absoluteValue" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 12.34
    },
    "percentageValue" : null
  },
  "position" : 2,
  "serviceableCountries" : [ "DE", "GB" ],
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 19.99
  },
  "activated" : false,
  "activeLogoSet" : null,
  "onlinePayment" : false,
  "activatable" : true,
  "_id" : "19fa0fd2-1b4d-474c-86fe-ea844ed0795e",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/19fa0fd2-1b4d-474c-86fe-ea844ed0795e"
    },
    "activate-payment-method" : {
      "href" : "https://api-shop.beyondshop.cloud/api/payment-methods/19fa0fd2-1b4d-474c-86fe-ea844ed0795e/activate"
    }
  }
}

Products

The products resource is used to manage products of a shop.

List 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?locale=en-US' -i -H 'Content-Type: application/hal+json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_embedded.products[].name

String

The name of the product.

_embedded.products[].sku

String

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

_embedded.products[].salesPrice

Object

The current sales price of the product.

_embedded.products[].listPrice

Object

The original sales price of the product.

_embedded.products[]._embedded.availability

Object

The information about the availability of the product.

_embedded.products[]._id

String

The immutable, unique identifier of the requested resource.

_links

Object

See Hypermedia

page

Object

See Pagination

Links

Relation Description

search

The link to product search endpoints.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 3199

{
  "_embedded" : {
    "products" : [ {
      "_id" : "d9ccb0ba-5c20-4d47-a0e2-4d699c56c8b4",
      "sku" : "123456789-001",
      "name" : "My product name",
      "salesPrice" : {
        "taxModel" : "NET",
        "currency" : "EUR",
        "amount" : 49.99,
        "derivedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 54.989,
          "taxRate" : 0.011
        }
      },
      "listPrice" : {
        "taxModel" : "NET",
        "currency" : "EUR",
        "amount" : 69.99,
        "derivedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 76.989,
          "taxRate" : 0.011
        }
      },
      "_embedded" : {
        "availability" : {
          "availabilityState" : "IN_STOCK",
          "availableStock" : 20,
          "stockThreshold" : 2,
          "purchasable" : true,
          "_links" : {
            "self" : {
              "href" : "https://api-shop.beyondshop.cloud/api/products/d9ccb0ba-5c20-4d47-a0e2-4d699c56c8b4/availability"
            }
          }
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/d9ccb0ba-5c20-4d47-a0e2-4d699c56c8b4"
        },
        "self-localized" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/d9ccb0ba-5c20-4d47-a0e2-4d699c56c8b4?locale=en-US"
        },
        "product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/d9ccb0ba-5c20-4d47-a0e2-4d699c56c8b4{?locale}",
          "templated" : true
        },
        "attributes" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/d9ccb0ba-5c20-4d47-a0e2-4d699c56c8b4/attributes{?locale}",
          "templated" : true
        },
        "attachments" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/d9ccb0ba-5c20-4d47-a0e2-4d699c56c8b4/attachments"
        },
        "images" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/d9ccb0ba-5c20-4d47-a0e2-4d699c56c8b4/images"
        },
        "amazon" : {
          "href" : "http://amazon/amazon-products/d9ccb0ba-5c20-4d47-a0e2-4d699c56c8b4"
        },
        "google-shopping" : {
          "href" : "http://google-shopping/google-products/d9ccb0ba-5c20-4d47-a0e2-4d699c56c8b4"
        },
        "default-image" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/d9ccb0ba-5c20-4d47-a0e2-4d699c56c8b4/default-image"
        },
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
          "templated" : true
        },
        "default-image-metadata" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998&download=no"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products?page=0&size=20"
    },
    "profile" : {
      "href" : "https://api-shop.beyondshop.cloud/api/profile/products"
    },
    "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 not be empty

name

String

The name of the product.

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.

salesPrice

Object

The current sales price of the product.

Must match the shop’s tax model. Must not be null

salesPrice.taxModel

String

The tax model of the sales price. Can be GROSS or NET.

salesPrice.amount

Number

Th amount of the sales price.

salesPrice.currency

String

The currency of the sales price.

listPrice

Object

The original sales price of the product.

listPrice.taxModel

String

The tax model of the list price. Can be GROSS or NET.

listPrice.amount

Number

The amount of the list price.

listPrice.currency

String

The currency of the list price.

onSale

Boolean

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

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.

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.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

Null

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?locale=en-US' -i -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer <Access token>' -d '{"sku":"123456789-001","name":"My product name","description":"My product description.","manufacturer":"The Manufacturer","essentialFeatures":"Some essential information","tags":["tag1","tag2"],"productIdentifiers":[{"type":"MPN","value":"ABC-123"},{"type":"EAN","value":"12345678"}],"salesPrice":{"taxModel":"NET","amount":49.99,"currency":"EUR"},"listPrice":{"taxModel":"NET","amount":29.99,"currency":"EUR"},"onSale":true,"visible":true,"taxClass":"REGULAR","shippingWeight":1000,"maxOrderQuantity":100,"shippingDimension":{"length":100,"width":100,"height":100},"refPrice":{"refQuantity":100,"unit":"GRAM","quantity":200,"price":null},"shippingPeriod":{"minDays":14,"maxDays":21,"displayUnit":"WEEKS"}}'

Example response

HTTP/1.1 201 Created
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Location: https://api-shop.beyondshop.cloud/api/products/643fb5ca-d87d-4366-ab63-cfb9e069f51e
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2451

{
  "sku" : "123456789-001",
  "salesPrice" : {
    "taxModel" : "NET",
    "currency" : "EUR",
    "amount" : 49.99,
    "derivedPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 54.989,
      "taxRate" : 0.1
    }
  },
  "listPrice" : {
    "taxModel" : "NET",
    "currency" : "EUR",
    "amount" : 29.99,
    "derivedPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 32.989,
      "taxRate" : 0.1
    }
  },
  "onSale" : true,
  "tags" : [ "tag1", "tag2" ],
  "productIdentifiers" : [ {
    "type" : "MPN",
    "value" : "ABC-123"
  }, {
    "type" : "EAN",
    "value" : "12345678"
  } ],
  "visible" : true,
  "taxClass" : "REGULAR",
  "shippingWeight" : 1000,
  "maxOrderQuantity" : 100,
  "shippingDimension" : {
    "length" : 100,
    "width" : 100,
    "height" : 100
  },
  "refPrice" : {
    "refQuantity" : 100,
    "unit" : "GRAM",
    "quantity" : 200,
    "price" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 24.995,
      "derivedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 27.495,
        "taxRate" : 0.1
      }
    }
  },
  "shippingPeriod" : {
    "minDays" : 14,
    "maxDays" : 21,
    "displayUnit" : "WEEKS"
  },
  "attributes" : [ ],
  "description" : "My product description.",
  "manufacturer" : "The Manufacturer",
  "essentialFeatures" : "Some essential information",
  "name" : "My product name",
  "_id" : "643fb5ca-d87d-4366-ab63-cfb9e069f51e",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/643fb5ca-d87d-4366-ab63-cfb9e069f51e"
    },
    "self-localized" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/643fb5ca-d87d-4366-ab63-cfb9e069f51e?locale=en-US"
    },
    "availability" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/643fb5ca-d87d-4366-ab63-cfb9e069f51e/availability"
    },
    "attributes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/643fb5ca-d87d-4366-ab63-cfb9e069f51e/attributes{?locale}",
      "templated" : true
    },
    "attachments" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/643fb5ca-d87d-4366-ab63-cfb9e069f51e/attachments"
    },
    "images" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/643fb5ca-d87d-4366-ab63-cfb9e069f51e/images"
    },
    "default-image" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/643fb5ca-d87d-4366-ab63-cfb9e069f51e/default-image"
    }
  }
}

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/e84a2b80-cc3a-4847-8e10-6456453e2f74?locale=en-US' -i -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.

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.

salesPrice

Object

The current sales price of the product.

salesPrice.taxModel

String

The tax model of the sales price. Can be GROSS or NET.

salesPrice.amount

Number

Th amount of the sales price.

salesPrice.currency

String

The currency of the sales price.

listPrice

Object

The original sales price of the product.

listPrice.taxModel

String

The tax model of the list price. Can be GROSS or NET.

listPrice.amount

Number

The amount of the list price.

listPrice.currency

String

The currency of the list price.

onSale

Boolean

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

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

Null

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.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.

_id

String

The immutable, unique identifier of the requested resource.

attributes

Array

The list of product attributes.

salesPrice.amount

Number

The amount of the list price.

salesPrice.derivedPrice

Object

The calculated price with taxes applied (read-only).

salesPrice.currency

String

The currency of the list price.

salesPrice.taxModel

String

The tax model of the list price. Can be GROSS or NET.

listPrice.amount

Number

The amount of the list price.

listPrice.derivedPrice

Object

The calculated price with taxes applied (read-only).

listPrice.currency

String

The currency of the list price.

listPrice.taxModel

String

The tax model of the list price. Can be GROSS or NET.

_links

Object

See Hypermedia

Links

Relation Description

product

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

self-localized

The templated self link to the product with the relevant localized parameters. See Hypermedia.

availability

The link to the information about product availability.

images

The link to the product image.

attributes

The link to the product properties.

attachments

The link to the product attachments.

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.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Last-Modified: Fri, 09 Feb 2018 14:26:52 GMT
ETag: "2"
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 3476

{
  "sku" : "123456789-001",
  "salesPrice" : {
    "taxModel" : "NET",
    "currency" : "EUR",
    "amount" : 49.99,
    "derivedPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 54.989,
      "taxRate" : 0.011
    }
  },
  "listPrice" : {
    "taxModel" : "NET",
    "currency" : "EUR",
    "amount" : 69.99,
    "derivedPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 76.989,
      "taxRate" : 0.011
    }
  },
  "onSale" : true,
  "tags" : [ "car", "dog", "cool" ],
  "productIdentifiers" : [ {
    "type" : "MPN",
    "value" : "ABC-123"
  }, {
    "type" : "EAN",
    "value" : "12345678"
  } ],
  "visible" : true,
  "taxClass" : "REGULAR",
  "shippingWeight" : 100,
  "maxOrderQuantity" : 4,
  "shippingDimension" : {
    "length" : 10,
    "width" : 50,
    "height" : 150
  },
  "refPrice" : {
    "refQuantity" : 100,
    "unit" : "GRAM",
    "quantity" : 200,
    "price" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 24.995,
      "derivedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 27.495,
        "taxRate" : 0.011
      }
    }
  },
  "shippingPeriod" : {
    "minDays" : 14,
    "maxDays" : null,
    "displayUnit" : "WEEKS"
  },
  "attributes" : [ {
    "namespace" : "custom",
    "name" : "size",
    "locale" : "en-US",
    "type" : "STRING",
    "value" : "L"
  }, {
    "namespace" : "seo",
    "name" : "slug",
    "locale" : "en-US",
    "type" : "STRING",
    "value" : "my-product"
  } ],
  "description" : "My product description.",
  "manufacturer" : "The Manufacturer",
  "essentialFeatures" : "Some essential information",
  "name" : "My product name",
  "_id" : "e84a2b80-cc3a-4847-8e10-6456453e2f74",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/e84a2b80-cc3a-4847-8e10-6456453e2f74"
    },
    "self-localized" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/e84a2b80-cc3a-4847-8e10-6456453e2f74?locale=en-US"
    },
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/e84a2b80-cc3a-4847-8e10-6456453e2f74{?locale}",
      "templated" : true
    },
    "availability" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/e84a2b80-cc3a-4847-8e10-6456453e2f74/availability"
    },
    "attributes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/e84a2b80-cc3a-4847-8e10-6456453e2f74/attributes{?locale}",
      "templated" : true
    },
    "attachments" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/e84a2b80-cc3a-4847-8e10-6456453e2f74/attachments"
    },
    "images" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/e84a2b80-cc3a-4847-8e10-6456453e2f74/images"
    },
    "amazon" : {
      "href" : "http://amazon/amazon-products/e84a2b80-cc3a-4847-8e10-6456453e2f74"
    },
    "google-shopping" : {
      "href" : "http://google-shopping/google-products/e84a2b80-cc3a-4847-8e10-6456453e2f74"
    },
    "default-image" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/e84a2b80-cc3a-4847-8e10-6456453e2f74/default-image"
    },
    "default-image-data" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "templated" : true
    },
    "default-image-metadata" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998&download=no"
    }
  }
}

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/d985a445-35da-4f79-8a86-5f089bd0f3a0?locale=en-US' -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":"My product name"},{"op":"replace","path":"/name","value":"patched name"},{"op":"replace","path":"/manufacturer","value":"patched manufacturer"},{"op":"add","path":"/tags/-","value":"new tag"},{"op":"remove","path":"/productIdentifiers"},{"op":"replace","path":"/salesPrice","value":{"taxModel":"NET","amount":999.0,"currency":"EUR"}}]'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
ETag: "3"
Last-Modified: Fri, 09 Feb 2018 14:26:44 GMT
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2756

{
  "sku" : "123456789-001",
  "salesPrice" : {
    "taxModel" : "NET",
    "currency" : "EUR",
    "amount" : 999,
    "derivedPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 1098.9,
      "taxRate" : 0.1
    }
  },
  "listPrice" : {
    "taxModel" : "NET",
    "currency" : "EUR",
    "amount" : 69.99,
    "derivedPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 76.989,
      "taxRate" : 0.1
    }
  },
  "onSale" : true,
  "tags" : [ "car", "dog", "cool", "new tag" ],
  "productIdentifiers" : [ ],
  "visible" : true,
  "taxClass" : "REGULAR",
  "shippingWeight" : 100,
  "maxOrderQuantity" : 4,
  "shippingDimension" : {
    "length" : 10,
    "width" : 50,
    "height" : 150
  },
  "refPrice" : {
    "refQuantity" : 100,
    "unit" : "GRAM",
    "quantity" : 200,
    "price" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 499.5,
      "derivedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 549.45,
        "taxRate" : 0.1
      }
    }
  },
  "shippingPeriod" : {
    "minDays" : 14,
    "maxDays" : null,
    "displayUnit" : "WEEKS"
  },
  "attributes" : [ {
    "namespace" : "custom",
    "name" : "size",
    "locale" : "en-US",
    "type" : "STRING",
    "value" : "L"
  }, {
    "namespace" : "seo",
    "name" : "slug",
    "locale" : "en-US",
    "type" : "STRING",
    "value" : "my-product"
  } ],
  "description" : "My product description.",
  "manufacturer" : "patched manufacturer",
  "essentialFeatures" : "Some essential information",
  "name" : "patched name",
  "_id" : "d985a445-35da-4f79-8a86-5f089bd0f3a0",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/d985a445-35da-4f79-8a86-5f089bd0f3a0"
    },
    "self-localized" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/d985a445-35da-4f79-8a86-5f089bd0f3a0?locale=en-US"
    },
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/d985a445-35da-4f79-8a86-5f089bd0f3a0{?locale}",
      "templated" : true
    },
    "availability" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/d985a445-35da-4f79-8a86-5f089bd0f3a0/availability"
    },
    "attributes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/d985a445-35da-4f79-8a86-5f089bd0f3a0/attributes{?locale}",
      "templated" : true
    },
    "attachments" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/d985a445-35da-4f79-8a86-5f089bd0f3a0/attachments"
    },
    "images" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/d985a445-35da-4f79-8a86-5f089bd0f3a0/images"
    },
    "default-image" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/d985a445-35da-4f79-8a86-5f089bd0f3a0/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/f60afce4-1f9b-4ab7-9758-445ee78962b3?locale=en-US' -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.","productIdentifiers":null,"manufacturer":"patched manufacturer"}'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
ETag: "3"
Last-Modified: Fri, 09 Feb 2018 14:26:50 GMT
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2745

{
  "sku" : "123456789-001",
  "salesPrice" : {
    "taxModel" : "NET",
    "currency" : "EUR",
    "amount" : 49.99,
    "derivedPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 54.989,
      "taxRate" : 0.1
    }
  },
  "listPrice" : {
    "taxModel" : "NET",
    "currency" : "EUR",
    "amount" : 69.99,
    "derivedPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 76.989,
      "taxRate" : 0.1
    }
  },
  "onSale" : true,
  "tags" : [ "car", "dog", "cool" ],
  "productIdentifiers" : [ ],
  "visible" : true,
  "taxClass" : "REGULAR",
  "shippingWeight" : 100,
  "maxOrderQuantity" : 4,
  "shippingDimension" : {
    "length" : 10,
    "width" : 50,
    "height" : 150
  },
  "refPrice" : {
    "refQuantity" : 100,
    "unit" : "GRAM",
    "quantity" : 200,
    "price" : {
      "taxModel" : "NET",
      "currency" : "EUR",
      "amount" : 24.995,
      "derivedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 27.495,
        "taxRate" : 0.1
      }
    }
  },
  "shippingPeriod" : {
    "minDays" : 14,
    "maxDays" : null,
    "displayUnit" : "WEEKS"
  },
  "attributes" : [ {
    "namespace" : "custom",
    "name" : "size",
    "locale" : "en-US",
    "type" : "STRING",
    "value" : "L"
  }, {
    "namespace" : "seo",
    "name" : "slug",
    "locale" : "en-US",
    "type" : "STRING",
    "value" : "my-product"
  } ],
  "description" : "patched description.",
  "manufacturer" : "patched manufacturer",
  "essentialFeatures" : "Some essential information",
  "name" : "patched name",
  "_id" : "f60afce4-1f9b-4ab7-9758-445ee78962b3",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/f60afce4-1f9b-4ab7-9758-445ee78962b3"
    },
    "self-localized" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/f60afce4-1f9b-4ab7-9758-445ee78962b3?locale=en-US"
    },
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/f60afce4-1f9b-4ab7-9758-445ee78962b3{?locale}",
      "templated" : true
    },
    "availability" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/f60afce4-1f9b-4ab7-9758-445ee78962b3/availability"
    },
    "attributes" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/f60afce4-1f9b-4ab7-9758-445ee78962b3/attributes{?locale}",
      "templated" : true
    },
    "attachments" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/f60afce4-1f9b-4ab7-9758-445ee78962b3/attachments"
    },
    "images" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/f60afce4-1f9b-4ab7-9758-445ee78962b3/images"
    },
    "default-image" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/f60afce4-1f9b-4ab7-9758-445ee78962b3/default-image"
    }
  }
}

Delete product

A DELETE request is used to delete a product.

Required scopes

prod:d

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/ad0c9d07-8b75-411e-afb0-d19a6d994e4c' -i -X DELETE -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

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 existing attribute values

A GET request is used to search for the attribute values that already exist for an attribute name. This is intended to be able to offer autosuggestion functionality when adding custom attributes to a product.

Required scopes

prod:r

Request parameters

Parameter Description

namespace

The attribute namespace to search in. If omitted, the namespace 'custom' is used.

attributeName

The attribute name to get values for.

query

The search query. A LIKE query is issued with this query as the search prefix.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/search/find-attribute-string-values?namespace=seo&attributeName=slug&query=my-' -i -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_embedded.attributes

Array

The list of product attributes.

_links

Object

See Hypermedia

Links

Relation Description

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 364

{
  "_embedded" : {
    "attributes" : [ {
      "attributeType" : "STRING",
      "stringValue" : "my-product",
      "numericValue" : null,
      "attributeValue" : "my-product"
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/search/find-attribute-string-values?namespace=seo&attributeName=slug&query=my-"
    }
  }
}

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=c' -i -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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 421

{
  "_embedded" : {
    "tags" : [ {
      "tag" : "car",
      "count" : 1
    }, {
      "tag" : "cool",
      "count" : 2
    }, {
      "tag" : "curious",
      "count" : 1
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/search/tags?startsWith=c&page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 3,
    "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 -H 'Authorization: Bearer <Access token>'

Links

Relation Description

find-by-sku

The link to find products by SKU.

find-attribute-string-values

The link to search existing attribute values for a given attribute name and search string.

tags

The link to find products by tags. Ordered by number of usage.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 577

{
  "_links" : {
    "find-by-sku" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/search/find-by-sku{?sku}",
      "templated" : true
    },
    "tags" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/search/tags{?startsWith,page,size,sort}",
      "templated" : true
    },
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/search"
    },
    "find-attribute-string-values" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/search/find-attribute-string-values{?namespace,attributeName,query,page,size,sort}",
      "templated" : true
    }
  }
}

List product meta-information

The products resource offers API meta-information when following the profile link.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/profile/products' -i

Example response

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

{
  "alps" : {
    "version" : "1.0",
    "descriptors" : [ {
      "id" : "product-representation",
      "href" : "https://api-shop.beyondshop.cloud/api/profile/products",
      "descriptors" : [ {
        "name" : "sku",
        "type" : "SEMANTIC"
      }, {
        "name" : "onSale",
        "type" : "SEMANTIC"
      }, {
        "name" : "tags",
        "type" : "SEMANTIC"
      }, {
        "name" : "productIdentifiers",
        "type" : "SEMANTIC"
      }, {
        "name" : "visible",
        "type" : "SEMANTIC"
      }, {
        "name" : "taxClass",
        "doc" : {
          "value" : "REGULAR, REDUCED, EXEMPT",
          "format" : "TEXT"
        },
        "type" : "SEMANTIC"
      }, {
        "name" : "shippingWeight",
        "type" : "SEMANTIC"
      }, {
        "name" : "maxOrderQuantity",
        "type" : "SEMANTIC"
      }, {
        "name" : "_id",
        "type" : "SEMANTIC"
      } ]
    }, {
      "id" : "create-products",
      "name" : "products",
      "type" : "UNSAFE",
      "rt" : "#product-representation"
    }, {
      "id" : "get-products",
      "name" : "products",
      "type" : "SAFE",
      "rt" : "#product-representation",
      "descriptors" : [ {
        "name" : "page",
        "doc" : {
          "value" : "The page to return.",
          "format" : "TEXT"
        },
        "type" : "SEMANTIC"
      }, {
        "name" : "size",
        "doc" : {
          "value" : "The size of the page to return.",
          "format" : "TEXT"
        },
        "type" : "SEMANTIC"
      }, {
        "name" : "sort",
        "doc" : {
          "value" : "The sorting criteria to use to calculate the content of the page.",
          "format" : "TEXT"
        },
        "type" : "SEMANTIC"
      } ]
    }, {
      "id" : "delete-product",
      "name" : "product",
      "type" : "IDEMPOTENT",
      "rt" : "#product-representation"
    }, {
      "id" : "get-product",
      "name" : "product",
      "type" : "SAFE",
      "rt" : "#product-representation"
    }, {
      "id" : "update-product",
      "name" : "product",
      "type" : "IDEMPOTENT",
      "rt" : "#product-representation"
    }, {
      "id" : "patch-product",
      "name" : "product",
      "type" : "UNSAFE",
      "rt" : "#product-representation"
    }, {
      "name" : "tags",
      "type" : "SAFE",
      "descriptors" : [ {
        "name" : "startsWith",
        "type" : "SEMANTIC"
      } ]
    }, {
      "name" : "find-by-sku",
      "type" : "SAFE",
      "descriptors" : [ {
        "name" : "sku",
        "type" : "SEMANTIC"
      } ]
    } ]
  }
}

Show product details

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

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/366a4546-b65f-4685-8eaf-71aa3bcaad55' -i -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 current sales price of the product.

listPrice

Object

The original sales price of the product.

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.

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. Identified by a qualified name consisting of namespace and name.

attributes[].namespace

String

The namespace of the product property. Groups all attribute names belonging to the same application in order to prevent name clashes. Example: a SEO app uses the namespace seo, whereas an Enterprise Management System uses ems. Both applications can use the same product property name, e.g. category by using another namespace. Examples: seo:category, ems:category.

attributes[].name

String

The name 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.

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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2685

{
  "_id" : "366a4546-b65f-4685-8eaf-71aa3bcaad55",
  "sku" : "1234567-7-7-7",
  "name" : "Cardigan - bordeaux",
  "salesPrice" : {
    "amount" : 1.0,
    "currency" : "EUR"
  },
  "listPrice" : {
    "amount" : 1.0,
    "currency" : "EUR"
  },
  "onSale" : false,
  "listPriceText" : "Old Price",
  "shippingDimension" : {
    "length" : 18,
    "width" : 17,
    "height" : 16
  },
  "refPrice" : {
    "refQuantity" : 100,
    "unit" : "GRAM",
    "quantity" : 200,
    "price" : {
      "amount" : 12.0,
      "currency" : "EUR"
    }
  },
  "availabilityState" : "IN_STOCK",
  "description" : "This product unifies comfortable materials and has a nice wear comfort. Slim-fit",
  "manufacturer" : "Posh Brand",
  "essentialFeatures" : "essential information shown during checkout",
  "tags" : [ "tag 2", "tag3", "tag_1" ],
  "attributes" : [ {
    "namespace" : "seo",
    "name" : "slug",
    "value" : "cardigan-bordeaux",
    "displayName" : "slug",
    "format" : null,
    "formattedValue" : "cardigan-bordeaux"
  }, {
    "namespace" : "seo",
    "name" : "title",
    "value" : "Cardigan, bordeaux",
    "displayName" : "title",
    "format" : null,
    "formattedValue" : "Cardigan, bordeaux"
  }, {
    "namespace" : "test",
    "name" : "half-life",
    "value" : 4468300.0,
    "displayName" : "half-life",
    "format" : null,
    "formattedValue" : 4468300.0
  }, {
    "namespace" : "test",
    "name" : "long",
    "value" : 1.0,
    "displayName" : "long",
    "format" : null,
    "formattedValue" : 1.0
  } ],
  "shippingPeriod" : {
    "minDays" : null,
    "maxDays" : 14,
    "displayUnit" : "WEEKS"
  },
  "_links" : {
    "default-image-data" : {
      "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/Cardigan.jpg?hash=e9a1ce5c0c6abfebec8fb1f6faf77dca7e6e7777{&width,height,upscale}",
      "templated" : true
    },
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/366a4546-b65f-4685-8eaf-71aa3bcaad55"
    },
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/366a4546-b65f-4685-8eaf-71aa3bcaad55{?projection}",
      "templated" : true
    },
    "additional-image-data" : [ {
      "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "templated" : true
    }, {
      "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/P7120105.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225999{&width,height,upscale}",
      "templated" : true
    }, {
      "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/P7120106.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281226000{&width,height,upscale}",
      "templated" : true
    } ]
  }
}

Show enhanced view of product details

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

Request parameters

Parameter Description

projection

The projection to apply in order to show an enhanced view of product details. Use enhancedProductProjection.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/5851c8c4-b416-46b9-ba4e-f94d0f6463b1?projection=enhancedProductProjection' -i -H 'Content-Type: application/json' -H 'Accept: application/hal+json'

Response body properties

Path Type Description

_id

String

The unique identifier of the product.

_indexedAt

String

The time of storing this document in the search index.

sku

String

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

salesPrice

Object

The current sales price of the product.

listPrice

Object

The original sales price of the product.

onSale

Boolean

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

name

String

The name of the product.

description

String

The description of the product.

manufacturer

String

The manufacturer of the product.

essentialFeatures

Null

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.

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.

attributes

Array

The product properties. Identified by a qualified name consisting of namespace and name.

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.

shippingPeriod

Object

The shipping period for this particular product.

availabilityState

String

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

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
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1582

{
  "_id" : "5851c8c4-b416-46b9-ba4e-f94d0f6463b1",
  "_indexedAt" : "2018-02-12T12:25:19.276",
  "sku" : "1234568-9-9-9",
  "name" : "Blue Jeans",
  "salesPrice" : {
    "amount" : 2.0,
    "currency" : "EUR"
  },
  "listPrice" : {
    "amount" : 2.0,
    "currency" : "EUR"
  },
  "onSale" : true,
  "listPriceText" : "Old Price",
  "shippingDimension" : {
    "length" : 17,
    "width" : 16,
    "height" : 15
  },
  "refPrice" : {
    "refQuantity" : 100,
    "unit" : "GRAM",
    "quantity" : 200,
    "price" : {
      "amount" : 12.0,
      "currency" : "EUR"
    }
  },
  "availabilityState" : "IN_STOCK",
  "description" : "Classic stone-washed blue-jeans. Slim-fit",
  "manufacturer" : "Posh Brand",
  "essentialFeatures" : null,
  "tags" : [ "tag6" ],
  "attributes" : [ ],
  "shippingPeriod" : {
    "minDays" : null,
    "maxDays" : 14,
    "displayUnit" : "WEEKS"
  },
  "_links" : {
    "default-image-data" : {
      "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/blue_jeans_1.jpg?hash=e9a1ce5c0c6abfebec8fb1f6faf77dca7e699999{&width,height,upscale}",
      "templated" : true
    },
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/5851c8c4-b416-46b9-ba4e-f94d0f6463b1"
    },
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/5851c8c4-b416-46b9-ba4e-f94d0f6463b1{?projection}",
      "templated" : true
    },
    "additional-image-data" : {
      "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "templated" : true
    }
  }
}

List products

A GET request is used to list all products.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products' -i -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 current sales price of the product.

_embedded.products[].listPrice

Object

The original sales price of the product.

_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[].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[]._links

Object

The links to receive further information related to the product.

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

String

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

_embedded.products[].refPrice.refQuantity

Number

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

_embedded.products[].refPrice.quantity

Number

The actual quantity in the product.

_embedded.products[].refPrice.unit

String

The unit corresponding to the quanity.

_embedded.products[].refPrice.price

Object

The actual 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[].listPriceText

String

The text that comes along with the list price.

_links

Object

See Hypermedia

page

Object

See Pagination

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 3730

{
  "_embedded" : {
    "products" : [ {
      "_id" : "b74cc3ec-cd3b-4b15-950c-2d4175922bad",
      "sku" : "1234567-7-7-7",
      "name" : "Cardigan - bordeaux",
      "salesPrice" : {
        "amount" : 1.0,
        "currency" : "EUR"
      },
      "listPrice" : {
        "amount" : 1.0,
        "currency" : "EUR"
      },
      "onSale" : false,
      "listPriceText" : "Old Price",
      "shippingDimension" : {
        "length" : 18,
        "width" : 17,
        "height" : 16
      },
      "refPrice" : {
        "refQuantity" : 100,
        "unit" : "GRAM",
        "quantity" : 200,
        "price" : {
          "amount" : 12.0,
          "currency" : "EUR"
        }
      },
      "availabilityState" : "IN_STOCK",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/Cardigan.jpg?hash=e9a1ce5c0c6abfebec8fb1f6faf77dca7e6e7777{&width,height,upscale}",
          "templated" : true
        },
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/b74cc3ec-cd3b-4b15-950c-2d4175922bad"
        },
        "product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/b74cc3ec-cd3b-4b15-950c-2d4175922bad{?projection}",
          "templated" : true
        }
      }
    }, {
      "_id" : "14e8ab4f-13ad-40f1-bda5-013bd9a312ff",
      "sku" : "1234568-8-8-8",
      "name" : "Beanie - olive",
      "salesPrice" : {
        "amount" : 3.0,
        "currency" : "EUR"
      },
      "listPrice" : {
        "amount" : 3.0,
        "currency" : "EUR"
      },
      "onSale" : false,
      "listPriceText" : "Old Price",
      "shippingDimension" : {
        "length" : 19,
        "width" : 18,
        "height" : 17
      },
      "refPrice" : {
        "refQuantity" : 100,
        "unit" : "GRAM",
        "quantity" : 200,
        "price" : {
          "amount" : 12.0,
          "currency" : "EUR"
        }
      },
      "availabilityState" : "IN_STOCK",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/14e8ab4f-13ad-40f1-bda5-013bd9a312ff"
        },
        "product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/14e8ab4f-13ad-40f1-bda5-013bd9a312ff{?projection}",
          "templated" : true
        }
      }
    }, {
      "_id" : "5898f9db-cad3-4d46-b889-e16067e66b83",
      "sku" : "1234568-9-9-9",
      "name" : "Blue Jeans",
      "salesPrice" : {
        "amount" : 2.0,
        "currency" : "EUR"
      },
      "listPrice" : {
        "amount" : 2.0,
        "currency" : "EUR"
      },
      "onSale" : true,
      "listPriceText" : "Old Price",
      "shippingDimension" : {
        "length" : 17,
        "width" : 16,
        "height" : 15
      },
      "refPrice" : {
        "refQuantity" : 100,
        "unit" : "GRAM",
        "quantity" : 200,
        "price" : {
          "amount" : 12.0,
          "currency" : "EUR"
        }
      },
      "availabilityState" : "IN_STOCK",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/blue_jeans_1.jpg?hash=e9a1ce5c0c6abfebec8fb1f6faf77dca7e699999{&width,height,upscale}",
          "templated" : true
        },
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/5898f9db-cad3-4d46-b889-e16067e66b83"
        },
        "product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/5898f9db-cad3-4d46-b889-e16067e66b83{?projection}",
          "templated" : true
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products?page=0&size=40"
    }
  },
  "page" : {
    "size" : 40,
    "totalElements" : 3,
    "totalPages" : 1,
    "number" : 0
  }
}

List products by tags

A GET request is used to search for products matching any tag of the list given by a client. The intention is to offer product search capabilities for the storefront.

Request parameters

Parameter Description

tag

The tags assigned to a product that MUST be matched for the search request.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/search/find-by-tags?tag=tag3' -i -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 current sales price of the product.

_embedded.products[].listPrice

Object

The original sales price of the product.

_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[].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[]._links

Object

The links to receive further information related to the product.

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

String

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

_embedded.products[].refPrice.refQuantity

Number

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

_embedded.products[].refPrice.quantity

Number

The actual quantity in the product.

_embedded.products[].refPrice.unit

String

The unit corresponding to the quanity.

_embedded.products[].refPrice.price

Object

The actual 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[].listPriceText

String

The text that comes along with the list price.

_links

Object

See Hypermedia

page

Object

See Pagination

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2551

{
  "_embedded" : {
    "products" : [ {
      "_id" : "e6e53069-0982-4377-a737-f1bd96371193",
      "sku" : "1234568-8-8-8",
      "name" : "Beanie - olive",
      "salesPrice" : {
        "amount" : 3.0,
        "currency" : "EUR"
      },
      "listPrice" : {
        "amount" : 3.0,
        "currency" : "EUR"
      },
      "onSale" : false,
      "listPriceText" : "Old Price",
      "shippingDimension" : {
        "length" : 19,
        "width" : 18,
        "height" : 17
      },
      "refPrice" : {
        "refQuantity" : 100,
        "unit" : "GRAM",
        "quantity" : 200,
        "price" : {
          "amount" : 12.0,
          "currency" : "EUR"
        }
      },
      "availabilityState" : "IN_STOCK",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/e6e53069-0982-4377-a737-f1bd96371193"
        },
        "product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/e6e53069-0982-4377-a737-f1bd96371193{?projection}",
          "templated" : true
        }
      }
    }, {
      "_id" : "e79a2854-8741-4ebc-8cee-4ef331ef7713",
      "sku" : "1234567-7-7-7",
      "name" : "Cardigan - bordeaux",
      "salesPrice" : {
        "amount" : 1.0,
        "currency" : "EUR"
      },
      "listPrice" : {
        "amount" : 1.0,
        "currency" : "EUR"
      },
      "onSale" : false,
      "listPriceText" : "Old Price",
      "shippingDimension" : {
        "length" : 18,
        "width" : 17,
        "height" : 16
      },
      "refPrice" : {
        "refQuantity" : 100,
        "unit" : "GRAM",
        "quantity" : 200,
        "price" : {
          "amount" : 12.0,
          "currency" : "EUR"
        }
      },
      "availabilityState" : "IN_STOCK",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/Cardigan.jpg?hash=e9a1ce5c0c6abfebec8fb1f6faf77dca7e6e7777{&width,height,upscale}",
          "templated" : true
        },
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/e79a2854-8741-4ebc-8cee-4ef331ef7713"
        },
        "product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/e79a2854-8741-4ebc-8cee-4ef331ef7713{?projection}",
          "templated" : true
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/search/find-by-tags?page=0&size=40&sort=createdAt,desc&sort=id,asc"
    }
  },
  "page" : {
    "size" : 40,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

List products by term

A GET request is used to search for products using a search query.

Request parameters

Parameter Description

query

The search term for the search request. If empty an unfiltered result is returned.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/search/find-by-search-term?query=slim+fit' -i -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 current sales price of the product.

_embedded.products[].listPrice

Object

The original sales price of the product.

_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[].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[]._links

Object

The links to receive further information related to the product.

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

String

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

_embedded.products[].refPrice.refQuantity

Number

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

_embedded.products[].refPrice.quantity

Number

The actual quantity in the product.

_embedded.products[].refPrice.unit

String

The unit corresponding to the quanity.

_embedded.products[].refPrice.price

Object

The actual 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[].listPriceText

String

The text that comes along with the list price.

_links

Object

See Hypermedia

page

Object

See Pagination

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2758

{
  "_embedded" : {
    "products" : [ {
      "_id" : "03da6299-b7a2-4b67-a098-cc6ff8feb3cf",
      "sku" : "1234567-7-7-7",
      "name" : "Cardigan - bordeaux",
      "salesPrice" : {
        "amount" : 1.0,
        "currency" : "EUR"
      },
      "listPrice" : {
        "amount" : 1.0,
        "currency" : "EUR"
      },
      "onSale" : false,
      "listPriceText" : "Old Price",
      "shippingDimension" : {
        "length" : 18,
        "width" : 17,
        "height" : 16
      },
      "refPrice" : {
        "refQuantity" : 100,
        "unit" : "GRAM",
        "quantity" : 200,
        "price" : {
          "amount" : 12.0,
          "currency" : "EUR"
        }
      },
      "availabilityState" : "IN_STOCK",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/Cardigan.jpg?hash=e9a1ce5c0c6abfebec8fb1f6faf77dca7e6e7777{&width,height,upscale}",
          "templated" : true
        },
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/03da6299-b7a2-4b67-a098-cc6ff8feb3cf"
        },
        "product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/03da6299-b7a2-4b67-a098-cc6ff8feb3cf{?projection}",
          "templated" : true
        }
      }
    }, {
      "_id" : "2ff5bf0e-ab18-4ef6-99a6-602b05216dd2",
      "sku" : "1234568-9-9-9",
      "name" : "Blue Jeans",
      "salesPrice" : {
        "amount" : 2.0,
        "currency" : "EUR"
      },
      "listPrice" : {
        "amount" : 2.0,
        "currency" : "EUR"
      },
      "onSale" : true,
      "listPriceText" : "Old Price",
      "shippingDimension" : {
        "length" : 17,
        "width" : 16,
        "height" : 15
      },
      "refPrice" : {
        "refQuantity" : 100,
        "unit" : "GRAM",
        "quantity" : 200,
        "price" : {
          "amount" : 12.0,
          "currency" : "EUR"
        }
      },
      "availabilityState" : "IN_STOCK",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/blue_jeans_1.jpg?hash=e9a1ce5c0c6abfebec8fb1f6faf77dca7e699999{&width,height,upscale}",
          "templated" : true
        },
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/2ff5bf0e-ab18-4ef6-99a6-602b05216dd2"
        },
        "product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/2ff5bf0e-ab18-4ef6-99a6-602b05216dd2{?projection}",
          "templated" : true
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/search/find-by-search-term?page=0&size=40&sort=id,asc"
    }
  },
  "page" : {
    "size" : 40,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

List products by category

A GET request is used to search for products using a category id.

Request parameters

Parameter Description

categoryId

The unique identifier of the category a product is assigned to. Can be used to query products.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/search/find-by-category?categoryId=7a506e9a-65ee-4c1e-8199-f22b329daa89' -i -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 current sales price of the product.

_embedded.products[].listPrice

Object

The original sales price of the product.

_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[].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[]._links

Object

The links to receive further information related to the product.

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

String

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

_embedded.products[].refPrice.refQuantity

Number

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

_embedded.products[].refPrice.quantity

Number

The actual quantity in the product.

_embedded.products[].refPrice.unit

String

The unit corresponding to the quanity.

_embedded.products[].refPrice.price

Object

The actual 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[].listPriceText

String

The text that comes along with the list price.

_links

Object

See Hypermedia

page

Object

See Pagination

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1572

{
  "_embedded" : {
    "products" : [ {
      "_id" : "01e4e5eb-fbc7-477a-92b7-afcc1f65efbd",
      "sku" : "1234567-7-7-7",
      "name" : "Cardigan - bordeaux",
      "salesPrice" : {
        "amount" : 1.0,
        "currency" : "EUR"
      },
      "listPrice" : {
        "amount" : 1.0,
        "currency" : "EUR"
      },
      "onSale" : false,
      "listPriceText" : "Old Price",
      "shippingDimension" : {
        "length" : 18,
        "width" : 17,
        "height" : 16
      },
      "refPrice" : {
        "refQuantity" : 100,
        "unit" : "GRAM",
        "quantity" : 200,
        "price" : {
          "amount" : 12.0,
          "currency" : "EUR"
        }
      },
      "availabilityState" : "IN_STOCK",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/Cardigan.jpg?hash=e9a1ce5c0c6abfebec8fb1f6faf77dca7e6e7777{&width,height,upscale}",
          "templated" : true
        },
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/01e4e5eb-fbc7-477a-92b7-afcc1f65efbd"
        },
        "product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/01e4e5eb-fbc7-477a-92b7-afcc1f65efbd{?projection}",
          "templated" : true
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/search/find-by-category?categoryId=7a506e9a-65ee-4c1e-8199-f22b329daa89&page=0&size=40&sort=id,asc"
    }
  },
  "page" : {
    "size" : 40,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

List products by query

A POST request is used to search for products using a query provided as request body.

Request body properties

Path Type Description

query

Object

The Elasticsearch query, see Search Request Query.

sort

String

The Elasticsearch sort, see Search Request Sort.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/search/find-by-query' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -d '{ "query": {"bool":{"filter":[{"term":{"tags":"tag_1"}},{"range":{"salesPrice.amount":{"lte":2.0}}},{"range":{"createdAt":{"gte":"now-1h"}}}]}}, "sort": "name"}'

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 current sales price of the product.

_embedded.products[].listPrice

Object

The original sales price of the product.

_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[].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[]._links

Object

The links to receive further information related to the product.

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

String

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

_embedded.products[].refPrice.refQuantity

Number

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

_embedded.products[].refPrice.quantity

Number

The actual quantity in the product.

_embedded.products[].refPrice.unit

String

The unit corresponding to the quanity.

_embedded.products[].refPrice.price

Object

The actual 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[].listPriceText

String

The text that comes along with the list price.

_links

Object

See Hypermedia

page

Object

See Pagination

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1509

{
  "_embedded" : {
    "products" : [ {
      "_id" : "e120c2b1-c516-477f-ac06-e70cf4a26195",
      "sku" : "1234567-7-7-7",
      "name" : "Cardigan - bordeaux",
      "salesPrice" : {
        "amount" : 1.0,
        "currency" : "EUR"
      },
      "listPrice" : {
        "amount" : 1.0,
        "currency" : "EUR"
      },
      "onSale" : false,
      "listPriceText" : "Old Price",
      "shippingDimension" : {
        "length" : 18,
        "width" : 17,
        "height" : 16
      },
      "refPrice" : {
        "refQuantity" : 100,
        "unit" : "GRAM",
        "quantity" : 200,
        "price" : {
          "amount" : 12.0,
          "currency" : "EUR"
        }
      },
      "availabilityState" : "IN_STOCK",
      "_links" : {
        "default-image-data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/storage-api/images/Cardigan.jpg?hash=e9a1ce5c0c6abfebec8fb1f6faf77dca7e6e7777{&width,height,upscale}",
          "templated" : true
        },
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/e120c2b1-c516-477f-ac06-e70cf4a26195"
        },
        "product" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/e120c2b1-c516-477f-ac06-e70cf4a26195{?projection}",
          "templated" : true
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/search/find-by-query?page=0&size=40"
    }
  },
  "page" : {
    "size" : 40,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

Example queries

A query for products having either tag cupcake or cake and a price greater or equal than 3.

{
  "query": {
    "bool": {
      "filter": [
        {
          "terms": {
            "tags": [
              "cupcake",
              "cake"
            ]
          }
        },
        {
          "range": {
            "salesPrice.amount": {
              "gte": 3
            }
          }
        }
      ]
    }
  }
}

A query for products having a custom integer attribute vol with a value less or equal than 14 and having either tag beer or wine.

{
  "query": {
    "bool": {
      "filter": [
        { "nested": {
            "path": "attributes",
            "query": {
              "bool": {
                "filter": [
                  { "term": { "attributes.name": "vol" } },
                  { "range": { "attributes.numericValue": { "lte": 14 } } }
                ]
              }
            }
          }
        },
        { "terms": { "tags": [ "beer", "wine" ] } }
      ]
    }
  }
}

A query for products having three custom attributes length, width and height each being less than 300.

{
  "query": {
    "bool": {
      "filter": [
        { "nested": {
            "path": "attributes",
            "query": {
              "bool": {
                "filter": [
                  { "term": { "attributes.name": "length" } },
                  { "range": { "attributes.numericValue": { "lt": 300 } } }
                ]
              }
            }
          }
        },
        { "nested": {
            "path": "attributes",
            "query": {
              "bool": {
                "filter": [
                  { "term": { "attributes.name": "width" } },
                  { "range": { "attributes.numericValue": { "lt": 300 } } }
                ]
              }
            }
          }
        },
        { "nested": {
            "path": "attributes",
            "query": {
              "bool": {
                "filter": [
                  { "term": { "attributes.name": "height" } },
                  { "range": { "attributes.numericValue": { "lt": 300 } } }
                ]
              }
            }
          }
        }
      ]
    }
  }
}

Product Attachments

List product attachments

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

Required scopes

prod:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/2f4db43c-f9e8-43c6-bd8a-86c608333c45/attachments' -i -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

Links

Relation Description

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2065

{
  "_embedded" : {
    "attachments" : [ {
      "mimeType" : "application/pdf",
      "length" : 1,
      "label" : "Handbuch",
      "_id" : "0f3d4fad-8481-4c81-8809-9c8b8b7148e9",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/2f4db43c-f9e8-43c6-bd8a-86c608333c45/attachments/0f3d4fad-8481-4c81-8809-9c8b8b7148e9"
        },
        "data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/attachments/1_my_attachment.pdf?hash=8a627f655c68f56dfbbf217ab7d5563281225801"
        },
        "metadata" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/attachments/1_my_attachment.pdf?hash=8a627f655c68f56dfbbf217ab7d5563281225801&download=no"
        },
        "attachment" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/2f4db43c-f9e8-43c6-bd8a-86c608333c45/attachments/0f3d4fad-8481-4c81-8809-9c8b8b7148e9"
        }
      }
    }, {
      "mimeType" : "application/pdf",
      "length" : 1,
      "label" : "Handbuch",
      "_id" : "4f60fa0d-e4ac-4ccb-8b00-9c1711089eb1",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/2f4db43c-f9e8-43c6-bd8a-86c608333c45/attachments/4f60fa0d-e4ac-4ccb-8b00-9c1711089eb1"
        },
        "data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/attachments/2_my_attachment.pdf?hash=8a627f655c68f56dfbbf217ab7d5563281225802"
        },
        "metadata" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/attachments/2_my_attachment.pdf?hash=8a627f655c68f56dfbbf217ab7d5563281225802&download=no"
        },
        "attachment" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/2f4db43c-f9e8-43c6-bd8a-86c608333c45/attachments/4f60fa0d-e4ac-4ccb-8b00-9c1711089eb1"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/2f4db43c-f9e8-43c6-bd8a-86c608333c45/attachments?page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

Show product attachment details

A GET request is used to retrieve a single attachment of a product.

Required scopes

prod:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/b1697de9-d965-454b-a0e2-d9e670671671/attachments/a5ae0be3-0cd5-4699-828a-0bf127bdbce9' -i -H 'Content-Type: application/hal+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.

mimeType

String

The media type of the product attachment.

length

Number

The length of the product attachment.

label

String

The label of the product attachment.

_links

Object

See Hypermedia

Links

Relation Description

data

Absolute URI to retrieve the binary data.

metadata

Absolute URI to retrieve the metadata.

attachment

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

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 803

{
  "mimeType" : "application/pdf",
  "length" : 1,
  "label" : "Handbuch",
  "_id" : "a5ae0be3-0cd5-4699-828a-0bf127bdbce9",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/b1697de9-d965-454b-a0e2-d9e670671671/attachments/a5ae0be3-0cd5-4699-828a-0bf127bdbce9"
    },
    "data" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/attachments/1_my_attachment.pdf?hash=8a627f655c68f56dfbbf217ab7d5563281225801"
    },
    "metadata" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/attachments/1_my_attachment.pdf?hash=8a627f655c68f56dfbbf217ab7d5563281225801&download=no"
    },
    "attachment" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/b1697de9-d965-454b-a0e2-d9e670671671/attachments/a5ae0be3-0cd5-4699-828a-0bf127bdbce9"
    }
  }
}

Add product attachment

A POST request is used to create an attachment and add it to a product.

Required scopes

prod:u

Request body properties

Path Type Description Constraints

dataUri

String

The templated relative download URL of the product attachment.

Must be a valid storage service URI (must contain a hash query parameter). Must not be null

mimeType

String

The media type of the product attachment.

Must not be null

length

Number

The length of the product attachment.

Must be greater than 1 and less than 9223372036854775807. Must not be null

label

String

The label of the product attachment.

Must not be null

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/8a4bb6bc-4a0b-4024-8bf2-430fb5342e4d/attachments' -i -X POST -H 'Content-Type: application/hal+json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>' -d '{"mimeType":"application/pdf","length":1,"label":"Handbuch","dataUri":"my_document_1.pdf?hash=8a627f655c68f56dfbbf217ab7d5563281225666"}'

Example response

HTTP/1.1 201 Created
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Location: https://api-shop.beyondshop.cloud/api/products/8a4bb6bc-4a0b-4024-8bf2-430fb5342e4d/attachments/81834340-35dc-4e13-a766-b3dde09d491f
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 799

{
  "mimeType" : "application/pdf",
  "length" : 1,
  "label" : "Handbuch",
  "_id" : "81834340-35dc-4e13-a766-b3dde09d491f",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/8a4bb6bc-4a0b-4024-8bf2-430fb5342e4d/attachments/81834340-35dc-4e13-a766-b3dde09d491f"
    },
    "data" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/attachments/my_document_1.pdf?hash=8a627f655c68f56dfbbf217ab7d5563281225666"
    },
    "metadata" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/attachments/my_document_1.pdf?hash=8a627f655c68f56dfbbf217ab7d5563281225666&download=no"
    },
    "attachment" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/8a4bb6bc-4a0b-4024-8bf2-430fb5342e4d/attachments/81834340-35dc-4e13-a766-b3dde09d491f"
    }
  }
}

Delete product attachment

A DELETE request is used to delete a product attachment.

Required scopes

prod:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/e1984968-0f11-4bfb-ae97-d4a45feab6f0/attachments/dab24f69-baf5-480c-975b-7dff3021a4de' -i -X DELETE -H 'Content-Type: application/hal+json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

Product Attribute Definitions

Attribute definitions provide meta data for attributes. An attribute definition is a precondition to create custom attributes

List product attribute definitions

A GET request will list the available product attribute definitions.

Required scopes

prad:r

Request parameters

Parameter Description

locale

The locale determining the localization context, e.g. the locale to retrieve the display name. Optional. Defaults to the shop locale.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/product-attribute-definitions?locale=en-US' -i -H 'Content-Type: application/hal+json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_embedded.product-attribute-definitions

Array

The list of product attribute definitions.

page

Object

See Pagination

_links

Object

See Hypermedia

Links

Relation Description

search

The link to product property definiton search endpoints.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1062

{
  "_embedded" : {
    "product-attribute-definitions" : [ {
      "name" : "colour",
      "namespace" : "custom",
      "format" : null,
      "type" : "STRING",
      "displayName" : "Color",
      "_id" : "f29b9431-119f-4128-8cf3-5dadf853b822",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/product-attribute-definitions/f29b9431-119f-4128-8cf3-5dadf853b822"
        },
        "product-attribute-definition" : {
          "href" : "https://api-shop.beyondshop.cloud/api/product-attribute-definitions/f29b9431-119f-4128-8cf3-5dadf853b822"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-attribute-definitions{?page,size,sort}",
      "templated" : true
    },
    "profile" : {
      "href" : "https://api-shop.beyondshop.cloud/api/profile/product-attribute-definitions"
    },
    "search" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-attribute-definitions/search"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

Show product attribute definition details

A GET request is used to retrieve a single attribute definition by id.

Required scopes

prad:r

Request parameters

Parameter Description

locale

The locale determining the localization context, e.g. the locale to retrieve the display name. Optional. Defaults to the shop locale.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/product-attribute-definitions/9fc15bc2-209f-4c13-8dcd-daed3f8c62e3?locale=en-US' -i -H 'Content-Type: application/hal+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.

namespace

String

The namespace of the product attribute definition.

name

String

The name of the product attribute definition.

type

String

The type of the product attribute definition. Optional. Defaults to STRING.

format

Null

(Optional) A format pattern that is applied to the value of each attribute instance.

displayName

String

The displayed name of the product attribute.

_links

Object

See Hypermedia

Links

Relation Description

product-attribute-definition

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

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Last-Modified: Fri, 09 Feb 2018 14:26:19 GMT
ETag: "1"
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 471

{
  "name" : "colour",
  "namespace" : "custom",
  "format" : null,
  "type" : "STRING",
  "displayName" : "Color",
  "_id" : "9fc15bc2-209f-4c13-8dcd-daed3f8c62e3",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-attribute-definitions/9fc15bc2-209f-4c13-8dcd-daed3f8c62e3"
    },
    "product-attribute-definition" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-attribute-definitions/9fc15bc2-209f-4c13-8dcd-daed3f8c62e3"
    }
  }
}

Create product attribute definition

A POST request is used to create an attribute definition.

Required scopes

prad:c

Request parameters

Parameter Description

locale

The locale determining the localization context, e.g. the locale to retrieve the display name. Optional. Defaults to the shop locale.

Request body properties

Path Type Description Constraints

namespace

String

The namespace of the product attribute definition.

Must not be null

name

String

The name of the product attribute definition.

Must not be null

displayName

String

The displayed name of the product attribute.

type

String

The type of the product attribute definition. Optional. Defaults to STRING.

Must not be null

format

String

(Optional) A format pattern that is applied to the value of each attribute instance.

Format pattern is not applicable for decimal numbers

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/product-attribute-definitions?locale=en-US' -i -X POST -H 'Content-Type: application/hal+json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>' -d '{"namespace":"custom","name":"filling_capacity","type":"NUMBER","displayName":"Filling Capacity","format":"#,###.## ml"}'

Example response

HTTP/1.1 201 Created
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
ETag: "1"
Last-Modified: Fri, 09 Feb 2018 14:26:22 GMT
Location: https://api-shop.beyondshop.cloud/api/product-attribute-definitions/750a98d8-e079-40bd-afc2-eeb9e628d52e
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 501

{
  "name" : "filling_capacity",
  "namespace" : "custom",
  "format" : "#,###.## ml",
  "type" : "NUMBER",
  "displayName" : "Filling Capacity",
  "_id" : "750a98d8-e079-40bd-afc2-eeb9e628d52e",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-attribute-definitions/750a98d8-e079-40bd-afc2-eeb9e628d52e"
    },
    "product-attribute-definition" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-attribute-definitions/750a98d8-e079-40bd-afc2-eeb9e628d52e"
    }
  }
}

Delete product attribute definition

A DELETE request is used to delete a product attribute definition. Only attribute definitions that are not used in any product can be deleted.

Required scopes

prad:d

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/product-attribute-definitions/6451cf17-35f3-44fd-a39d-a5275ea30e7f' -i -X DELETE -H 'Content-Type: application/hal+json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

Update product attribute definition

A PATCH request is used to update a product attribute definition. The namespace, name, and type fields cannot be changed. The displayName that is updated depends on the locale parameter.

Required scopes

prad:u

Request parameters

Parameter Description

locale

The locale determining the localization context, e.g. the locale to retrieve the display name. Optional. Defaults to the shop locale.

Request body properties

Path Type Description

displayName

String

The displayed name of the product attribute.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/product-attribute-definitions/090ad3f3-aaed-4ce1-b257-9067a9fa0ab1?locale=en-US' -i -X PATCH -H 'Content-Type: application/hal+json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>' -d '{"displayName":"Color of the item"}'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
ETag: "2"
Last-Modified: Fri, 09 Feb 2018 14:26:11 GMT
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 483

{
  "name" : "colour",
  "namespace" : "custom",
  "format" : null,
  "type" : "STRING",
  "displayName" : "Color of the item",
  "_id" : "090ad3f3-aaed-4ce1-b257-9067a9fa0ab1",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-attribute-definitions/090ad3f3-aaed-4ce1-b257-9067a9fa0ab1"
    },
    "product-attribute-definition" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-attribute-definitions/090ad3f3-aaed-4ce1-b257-9067a9fa0ab1"
    }
  }
}

A search resource is used as entry point for links to sub-resources offering attribute definition searches. Currently the following search options are offered:

Find existing attribute definitions by namespace and name

A GET request is used to search for an attribute definition by namespace and name.

Required scopes

prad:r

Request parameters

Parameter Description

namespace

The attribute namespace to search in. If omitted, the namespace 'custom' is used.

name

The name of the product attribute definition.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/product-attribute-definitions/search/find-by-namespace-and-name?namespace=custom&name=colour' -i -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Last-Modified: Fri, 09 Feb 2018 14:26:16 GMT
ETag: "1"
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 471

{
  "name" : "colour",
  "namespace" : "custom",
  "format" : null,
  "type" : "STRING",
  "displayName" : "Color",
  "_id" : "362b0cdf-1b12-4fa6-ac48-cf9a046c4795",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-attribute-definitions/362b0cdf-1b12-4fa6-ac48-cf9a046c4795"
    },
    "product-attribute-definition" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-attribute-definitions/362b0cdf-1b12-4fa6-ac48-cf9a046c4795"
    }
  }
}

Find existing attribute definitions by namespace and query

A GET request is used to search for an attribute definition that already exists by namespace and prefix of the name.

Required scopes

prad:r

Request parameters

Parameter Description

namespace

The attribute namespace to search in. If omitted, the namespace 'custom' is used.

query

The search query. A LIKE query is issued with this query as the search prefix.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/product-attribute-definitions/search/find-by-namespace-and-query?namespace=custom&query=col' -i -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_embedded.product-attribute-definitions

Array

The list of product attribute definitions.

_links

Object

See Hypermedia

page

Object

See Pagination

Links

Relation Description

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 888

{
  "_embedded" : {
    "product-attribute-definitions" : [ {
      "name" : "colour",
      "namespace" : "custom",
      "format" : null,
      "type" : "STRING",
      "displayName" : "Color",
      "_id" : "28865068-d715-4ff9-941f-7273ef024e3c",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/product-attribute-definitions/28865068-d715-4ff9-941f-7273ef024e3c"
        },
        "product-attribute-definition" : {
          "href" : "https://api-shop.beyondshop.cloud/api/product-attribute-definitions/28865068-d715-4ff9-941f-7273ef024e3c"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/product-attribute-definitions/search/find-by-namespace-and-query?namespace=custom&query=col&page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

Product Availability

Show product availability details

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

Required scopes

prda:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/0d6ead91-94e9-45cd-a0f5-3ea5d30c3849/availability?locale=en-US' -i -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

availableStock

Number

The number of products available in stock.

stockThreshold

Number

The threshold of the available stock level.

purchasable

Boolean

Indicates if a product can be purchased. Can be true or false.

availabilityState

String

The current availability state of the product. If the related product is not in a purchasable availability state, it will be NOT_AVAILABLE. If the stock level is equal or lower than this value, the availability state is LOW_STOCK. Can be IN_STOCK, LOW_STOCK, NOT_AVAILABLE or OUT_OF_STOCK.

_links

Object

See Hypermedia

Links

Relation Description

product

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

disable-purchasability

The link to disable purchasability.

disable-stock-management

The link to disable the stock management.

adjust-available-stock

The link to adjust the available stock.

update-stock-threshold

The link to update the stock threshold.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1026

{
  "availabilityState" : "IN_STOCK",
  "availableStock" : 20,
  "stockThreshold" : 2,
  "purchasable" : true,
  "_links" : {
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/0d6ead91-94e9-45cd-a0f5-3ea5d30c3849"
    },
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/0d6ead91-94e9-45cd-a0f5-3ea5d30c3849/availability"
    },
    "disable-purchasability" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/0d6ead91-94e9-45cd-a0f5-3ea5d30c3849/availability/disable-purchasability"
    },
    "adjust-available-stock" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/0d6ead91-94e9-45cd-a0f5-3ea5d30c3849/availability/adjust-available-stock"
    },
    "update-stock-threshold" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/0d6ead91-94e9-45cd-a0f5-3ea5d30c3849/availability/update-stock-threshold"
    },
    "disable-stock-management" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/0d6ead91-94e9-45cd-a0f5-3ea5d30c3849/availability/disable-stock-management"
    }
  }
}

Enable stock management

A POST request is used to enable stock management for a product.

Required scopes

prda:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/a3a46f23-00ad-412d-9105-dea1966d091e/availability/enable-stock-management?locale=en-US' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>' -d '{ "initialAvailableStock" : 100, "stockThreshold" : 2 }'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Location: https://api-shop.beyondshop.cloud/api/products/a3a46f23-00ad-412d-9105-dea1966d091e/availability
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1027

{
  "availabilityState" : "IN_STOCK",
  "availableStock" : 100,
  "stockThreshold" : 2,
  "purchasable" : true,
  "_links" : {
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/a3a46f23-00ad-412d-9105-dea1966d091e"
    },
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/a3a46f23-00ad-412d-9105-dea1966d091e/availability"
    },
    "disable-purchasability" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/a3a46f23-00ad-412d-9105-dea1966d091e/availability/disable-purchasability"
    },
    "adjust-available-stock" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/a3a46f23-00ad-412d-9105-dea1966d091e/availability/adjust-available-stock"
    },
    "update-stock-threshold" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/a3a46f23-00ad-412d-9105-dea1966d091e/availability/update-stock-threshold"
    },
    "disable-stock-management" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/a3a46f23-00ad-412d-9105-dea1966d091e/availability/disable-stock-management"
    }
  }
}

Disable stock management

A POST request is used to disable stock management for a product.

Required scopes

prda:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/a308f800-1679-496d-b8a0-e71e034485a6/availability/disable-stock-management' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>' -d 'locale=en-US'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Location: https://api-shop.beyondshop.cloud/api/products/a308f800-1679-496d-b8a0-e71e034485a6/availability
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 701

{
  "availabilityState" : "IN_STOCK",
  "availableStock" : null,
  "stockThreshold" : null,
  "purchasable" : true,
  "_links" : {
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/a308f800-1679-496d-b8a0-e71e034485a6"
    },
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/a308f800-1679-496d-b8a0-e71e034485a6/availability"
    },
    "disable-purchasability" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/a308f800-1679-496d-b8a0-e71e034485a6/availability/disable-purchasability"
    },
    "enable-stock-management" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/a308f800-1679-496d-b8a0-e71e034485a6/availability/enable-stock-management"
    }
  }
}

Adjust stock level

A POST request is used to adjust the available stock of a product.

Required scopes

prda:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/7a5f01ca-8941-4ecf-9733-e6937955c846/availability/adjust-available-stock?locale=en-US' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>' -d '{ "relativeAmount" : -1 }'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Location: https://api-shop.beyondshop.cloud/api/products/7a5f01ca-8941-4ecf-9733-e6937955c846/availability
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1025

{
  "availabilityState" : "IN_STOCK",
  "availableStock" : 9,
  "stockThreshold" : 2,
  "purchasable" : true,
  "_links" : {
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/7a5f01ca-8941-4ecf-9733-e6937955c846"
    },
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/7a5f01ca-8941-4ecf-9733-e6937955c846/availability"
    },
    "disable-purchasability" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/7a5f01ca-8941-4ecf-9733-e6937955c846/availability/disable-purchasability"
    },
    "adjust-available-stock" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/7a5f01ca-8941-4ecf-9733-e6937955c846/availability/adjust-available-stock"
    },
    "update-stock-threshold" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/7a5f01ca-8941-4ecf-9733-e6937955c846/availability/update-stock-threshold"
    },
    "disable-stock-management" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/7a5f01ca-8941-4ecf-9733-e6937955c846/availability/disable-stock-management"
    }
  }
}

Update safety stock

A POST request is used to update the the stock threshold of a product.

Required scopes

prda:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/375401c1-f22a-42b5-87a4-06c798ceb564/availability/update-stock-threshold?locale=en-US' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>' -d '{ "stockThreshold" : 5 }'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Location: https://api-shop.beyondshop.cloud/api/products/375401c1-f22a-42b5-87a4-06c798ceb564/availability
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1026

{
  "availabilityState" : "IN_STOCK",
  "availableStock" : 10,
  "stockThreshold" : 5,
  "purchasable" : true,
  "_links" : {
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/375401c1-f22a-42b5-87a4-06c798ceb564"
    },
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/375401c1-f22a-42b5-87a4-06c798ceb564/availability"
    },
    "disable-purchasability" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/375401c1-f22a-42b5-87a4-06c798ceb564/availability/disable-purchasability"
    },
    "adjust-available-stock" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/375401c1-f22a-42b5-87a4-06c798ceb564/availability/adjust-available-stock"
    },
    "update-stock-threshold" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/375401c1-f22a-42b5-87a4-06c798ceb564/availability/update-stock-threshold"
    },
    "disable-stock-management" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/375401c1-f22a-42b5-87a4-06c798ceb564/availability/disable-stock-management"
    }
  }
}

Enable purchasability

A POST request is used to enable purchasability for a product.

Required scopes

prda:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/719053ab-dd28-4482-87b9-f3383156ce96/availability/enable-purchasability' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>' -d 'locale=en-US'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Location: https://api-shop.beyondshop.cloud/api/products/719053ab-dd28-4482-87b9-f3383156ce96/availability
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 701

{
  "availabilityState" : "IN_STOCK",
  "availableStock" : null,
  "stockThreshold" : null,
  "purchasable" : true,
  "_links" : {
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/719053ab-dd28-4482-87b9-f3383156ce96"
    },
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/719053ab-dd28-4482-87b9-f3383156ce96/availability"
    },
    "disable-purchasability" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/719053ab-dd28-4482-87b9-f3383156ce96/availability/disable-purchasability"
    },
    "enable-stock-management" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/719053ab-dd28-4482-87b9-f3383156ce96/availability/enable-stock-management"
    }
  }
}

Disable purchasability

A POST request is used to disable purchasability for a product.

Required scopes

prda:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/28a7391c-ef47-4bc1-bc7d-6949a14683ce/availability/disable-purchasability' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>' -d 'locale=en-US'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Location: https://api-shop.beyondshop.cloud/api/products/28a7391c-ef47-4bc1-bc7d-6949a14683ce/availability
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 705

{
  "availabilityState" : "NOT_AVAILABLE",
  "availableStock" : null,
  "stockThreshold" : null,
  "purchasable" : false,
  "_links" : {
    "product" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/28a7391c-ef47-4bc1-bc7d-6949a14683ce"
    },
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/28a7391c-ef47-4bc1-bc7d-6949a14683ce/availability"
    },
    "enable-purchasability" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/28a7391c-ef47-4bc1-bc7d-6949a14683ce/availability/enable-purchasability"
    },
    "enable-stock-management" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/28a7391c-ef47-4bc1-bc7d-6949a14683ce/availability/enable-stock-management"
    }
  }
}

Custom Product Attributes

The attributes resource is used to manage additional user-defined attributes on any type supporting this facility.

Attribute types

These are the basic types supported by the API.

Type Description

BOOLEAN

Boolean value (true,false)

STRING

String value (max. 4kb)

LONG

Long integer

DOUBLE

Double-precision floating number

DATE_TIME

Date and time without timezone information (UTC)

MONEY

Money value

DATA

Byte array

Localization

All attributes can be localized, so that you can assign one specific value per attribute name and locale. If you want non-localized attributes, just use an empty locale (""), which is equivalent to the "root locale".

Custom attributes

Request parameters for custom attributes endpoints

Parameter Description

locale

Optional LocaleCode parameter

Response structure for custom attributes endpoints

Path Type Description

_embedded.attributes[].namespace

String

Namespace

_embedded.attributes[].name

String

Name

_embedded.attributes[].locale

String

Locale

_embedded.attributes[].value

Boolean

Value

_embedded.attributes[].type

String

Type

Create custom product attribute

Required scopes

prod:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/9f01d260-d23b-4abb-8fc7-ca5a38977370/attributes' -i -X POST -H 'Content-Type: application/hal+json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>' -d '{"namespace":"my_test_namespace111","name":"my_test_attr_name111","locale":"en_US","type":"STRING","value":"my_test_string_value"}'

Example response

HTTP/1.1 201 Created
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Location: https://api-shop.beyondshop.cloud/api/products/9f01d260-d23b-4abb-8fc7-ca5a38977370/attributes

List custom product attributes

To receive product custom attributes list optional locale parameter can be specified.

Required scopes

prod:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/30e9760b-a79d-4e73-b357-957478ef2382/attributes?locale=de-DE' -i -H 'Content-Type: application/hal+json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_embedded.attributes[].namespace

String

The namespace of the product attribute.

_embedded.attributes[].name

String

The name of the product attribute.

_embedded.attributes[].locale

String

The locale of the product attribute.

_embedded.attributes[].value

Varies

The value of the product attribute.

_embedded.attributes[].type

String

The type of the product attribute.

_links

Object

See Hypermedia

page

Object

See Pagination

Links

Relation Description

owner

The link to the owner of the product.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 3286

{
  "_embedded" : {
    "attributes" : [ {
      "namespace" : "_dummy_namespace",
      "name" : "_dummy_attr_different_locale",
      "locale" : "de-DE",
      "type" : "STRING",
      "value" : "attrappe-produkt",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/30e9760b-a79d-4e73-b357-957478ef2382/attributes/_dummy_namespace/_dummy_attr_different_locale?locale=de-DE"
        },
        "owner" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/30e9760b-a79d-4e73-b357-957478ef2382"
        }
      }
    }, {
      "namespace" : "_dummy_namespace",
      "name" : "_dummy_attr_undefined_locale",
      "locale" : "",
      "type" : "NUMBER",
      "value" : 42.0,
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/30e9760b-a79d-4e73-b357-957478ef2382/attributes/_dummy_namespace/_dummy_attr_undefined_locale?locale="
        },
        "owner" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/30e9760b-a79d-4e73-b357-957478ef2382"
        }
      }
    }, {
      "namespace" : "mbo",
      "name" : "flag",
      "locale" : "",
      "type" : "NUMBER",
      "value" : 42.0,
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/30e9760b-a79d-4e73-b357-957478ef2382/attributes/mbo/flag?locale="
        },
        "owner" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/30e9760b-a79d-4e73-b357-957478ef2382"
        }
      }
    }, {
      "namespace" : "namespace_seo",
      "name" : "attr_different_locale",
      "locale" : "de-DE",
      "type" : "STRING",
      "value" : "mein-produkt",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/30e9760b-a79d-4e73-b357-957478ef2382/attributes/namespace_seo/attr_different_locale?locale=de-DE"
        },
        "owner" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/30e9760b-a79d-4e73-b357-957478ef2382"
        }
      }
    }, {
      "namespace" : "namespace_seo",
      "name" : "attr_undefined_locale",
      "locale" : "",
      "type" : "NUMBER",
      "value" : 42.0,
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/30e9760b-a79d-4e73-b357-957478ef2382/attributes/namespace_seo/attr_undefined_locale?locale="
        },
        "owner" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/30e9760b-a79d-4e73-b357-957478ef2382"
        }
      }
    }, {
      "namespace" : "seo",
      "name" : "slug",
      "locale" : "de-DE",
      "type" : "STRING",
      "value" : "mein-produkt",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/30e9760b-a79d-4e73-b357-957478ef2382/attributes/seo/slug?locale=de-DE"
        },
        "owner" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/30e9760b-a79d-4e73-b357-957478ef2382"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/30e9760b-a79d-4e73-b357-957478ef2382/attributes?locale=de-DE"
    },
    "owner" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/30e9760b-a79d-4e73-b357-957478ef2382"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 6,
    "totalPages" : 1,
    "number" : 0
  }
}

List custom product attributes by namespace

Required scopes

prod:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/a7263a79-ca53-4239-9547-bcb6c986d4e8/attributes/seo?locale=en-US' -i -H 'Content-Type: application/hal+json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_embedded.attributes[].namespace

String

The namespace of the product attribute.

_embedded.attributes[].name

String

The name of the product attribute.

_embedded.attributes[].locale

String

The locale of the product attribute.

_embedded.attributes[].value

String

The value of the product attribute.

_embedded.attributes[].type

String

The type of the product attribute.

_links

Object

See Hypermedia

page

Object

See Pagination

Links

Relation Description

owner

The link to the owner of the product.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 854

{
  "_embedded" : {
    "attributes" : [ {
      "namespace" : "seo",
      "name" : "slug",
      "locale" : "en-US",
      "type" : "STRING",
      "value" : "my-product",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/a7263a79-ca53-4239-9547-bcb6c986d4e8/attributes/seo/slug?locale=en-US"
        },
        "owner" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/a7263a79-ca53-4239-9547-bcb6c986d4e8"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/a7263a79-ca53-4239-9547-bcb6c986d4e8/attributes?locale=en-US"
    },
    "owner" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/a7263a79-ca53-4239-9547-bcb6c986d4e8"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

List custom product attributes by namespace and attribute name

Required scopes

prod:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/9dde5124-c01d-4ed5-a5ed-7ec4cc1456c8/attributes/namespace_seo/attr_different_locale?locale=de-DE' -i -H 'Content-Type: application/hal+json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_embedded.attributes[].namespace

String

The namespace of the product attribute.

_embedded.attributes[].name

String

The name of the product attribute.

_embedded.attributes[].locale

String

The locale of the product attribute.

_embedded.attributes[].value

String

The value of the product attribute.

_embedded.attributes[].type

String

The type of the product attribute.

_links

Object

See Hypermedia

page

Object

See Pagination

Links

Relation Description

owner

The link to the owner of the product.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 946

{
  "_embedded" : {
    "attributes" : [ {
      "namespace" : "namespace_seo",
      "name" : "attr_different_locale",
      "locale" : "de-DE",
      "type" : "STRING",
      "value" : "mein-produkt",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/9dde5124-c01d-4ed5-a5ed-7ec4cc1456c8/attributes/namespace_seo/attr_different_locale?locale=de-DE"
        },
        "owner" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/9dde5124-c01d-4ed5-a5ed-7ec4cc1456c8"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/9dde5124-c01d-4ed5-a5ed-7ec4cc1456c8/attributes/namespace_seo/attr_different_locale?locale=de-DE"
    },
    "owner" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/9dde5124-c01d-4ed5-a5ed-7ec4cc1456c8"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

Delete custom product attribute

Required scopes

prod:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/781dd1f6-f640-4138-8887-ae5a4b1f23ca/attributes/seo/slug' -i -X DELETE -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

Product Images

List product images

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

Required scopes

prod:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/e83cedd3-7f2d-40eb-98d2-e4ad113f9875/images' -i -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

Links

Relation Description

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1911

{
  "_embedded" : {
    "images" : [ {
      "_id" : "4cdcb9d2-06f9-48ce-890b-1a7210cdc505",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/e83cedd3-7f2d-40eb-98d2-e4ad113f9875/images/4cdcb9d2-06f9-48ce-890b-1a7210cdc505"
        },
        "data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
          "templated" : true
        },
        "metadata" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998&download=no"
        },
        "image" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/e83cedd3-7f2d-40eb-98d2-e4ad113f9875/images/4cdcb9d2-06f9-48ce-890b-1a7210cdc505"
        }
      }
    }, {
      "_id" : "9401cf76-f9d1-4afe-984c-c144a09ecb88",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/e83cedd3-7f2d-40eb-98d2-e4ad113f9875/images/9401cf76-f9d1-4afe-984c-c144a09ecb88"
        },
        "data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/P7120105.png?hash=8a627f655c68f56dfbbf217ab7d5563281225999{&width,height,upscale}",
          "templated" : true
        },
        "metadata" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/P7120105.png?hash=8a627f655c68f56dfbbf217ab7d5563281225999&download=no"
        },
        "image" : {
          "href" : "https://api-shop.beyondshop.cloud/api/products/e83cedd3-7f2d-40eb-98d2-e4ad113f9875/images/9401cf76-f9d1-4afe-984c-c144a09ecb88"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/e83cedd3-7f2d-40eb-98d2-e4ad113f9875/images?page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

Show product image details

A GET request is used to retrieve a single image of a product.

Required scopes

prod:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/bc4cfd61-43e5-499a-9ef7-0b2b4efa2e28/images/d44aa3c9-baa2-47f1-ba16-d97f326d6c99' -i -H 'Content-Type: application/hal+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.

_links

Object

See Hypermedia

Links

Relation Description

image

The link to the product image.

data

Download URL of the product image.

metadata

The URL to the image metadata of the product image.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 739

{
  "_id" : "d44aa3c9-baa2-47f1-ba16-d97f326d6c99",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/bc4cfd61-43e5-499a-9ef7-0b2b4efa2e28/images/d44aa3c9-baa2-47f1-ba16-d97f326d6c99"
    },
    "data" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "templated" : true
    },
    "metadata" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998&download=no"
    },
    "image" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/bc4cfd61-43e5-499a-9ef7-0b2b4efa2e28/images/d44aa3c9-baa2-47f1-ba16-d97f326d6c99"
    }
  }
}

Add product image

A POST request is used to create an image and add it to a product.

Required scopes

prod:u

Request body properties

Path Type Description Constraints

dataUri

String

The templated relative download URL of the product image.

Must be a valid storage service URI (must contain a hash query parameter). Must not be null

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/3291b7e0-dbfd-4d33-8502-662746a02080/images' -i -X POST -H 'Content-Type: application/hal+json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>' -d '{"dataUri":"P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998"}'

Example response

HTTP/1.1 201 Created
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Location: https://api-shop.beyondshop.cloud/api/products/3291b7e0-dbfd-4d33-8502-662746a02080/images/5bb41d4f-5cd4-49f8-ade0-f5ea69fffe84
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 739

{
  "_id" : "5bb41d4f-5cd4-49f8-ade0-f5ea69fffe84",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/3291b7e0-dbfd-4d33-8502-662746a02080/images/5bb41d4f-5cd4-49f8-ade0-f5ea69fffe84"
    },
    "data" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998{&width,height,upscale}",
      "templated" : true
    },
    "metadata" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/P7120104.JPG?hash=8a627f655c68f56dfbbf217ab7d5563281225998&download=no"
    },
    "image" : {
      "href" : "https://api-shop.beyondshop.cloud/api/products/3291b7e0-dbfd-4d33-8502-662746a02080/images/5bb41d4f-5cd4-49f8-ade0-f5ea69fffe84"
    }
  }
}

Delete product image

A DELETE request is used to delete a product image.

Required scopes

prod:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/9e5d9d0f-df7e-4fbd-b195-cdc08af193d1/images/d6ebdc0d-4582-4e33-ba4f-bc10f41d7134' -i -X DELETE -H 'Content-Type: application/hal+json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

Assign product image as default image

A PUT request is used to assign a product image as the default image. The request contains a single URI of the image to assign.

Required scopes

prod:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/products/e52c1984-abe7-4b7d-af6c-fd05024e1bc1/default-image' -i -X PUT -H 'Content-Type: text/uri-list' -H 'Accept: application/json' -H 'Authorization: Bearer <Access token>' -d 'http://localhost/products/images/20d274a7-442d-46a7-a8e8-01e81720eda6'

Example response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

Shipping Zones

The shipping zones resource is used to get information about shipping zones of this shop.

Shipping zones hold shipping methods that are applicable inside this shipping zone.

Show shipping zone details

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

Required scopes

shpz:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/shipping-zones/7908a89d-fc48-408f-ba23-846f8a08fbc5' -i -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 shipping zone in the merchant administration in relation to other shipping zones.

shippingMethods

Array

The shipping methods assigned to this shipping zone.

_links

Object

See Hypermedia

name

String

The name of the shipping zone.

serviceableCountries

Array

The list of countries this shipping zone applies to.

shippingMethods[]._id

String

The immutable, unique identifier of the requested resource.

shippingMethods[].weightBasedPrice

Null

The price depending on the package weight.

shippingMethods[].fixedPrice

Object

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

shippingMethods[].position

Number

The sorting position of the shipping method in the merchant administration in relation to other shipping methods.

shippingMethods[].name

String

The name of the shipping method.

shippingMethods[].description

String

description

shippingMethods[].taxClass

String

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

shippingMethods[].freeShippingValue

Object

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

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1048

{
  "name" : "BE-NL-LU",
  "serviceableCountries" : [ "BE", "LU", "NL" ],
  "position" : 2,
  "shippingMethods" : [ {
    "name" : "Standard Shipping 2",
    "description" : "Standard Shipping",
    "taxClass" : "REGULAR",
    "position" : 0,
    "freeShippingValue" : {
      "currency" : "EUR",
      "amount" : 400
    },
    "fixedPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "weightBasedPrice" : null,
    "_id" : "85036b51-215a-42df-acbf-1b8f30d506d5",
    "_links" : {
      "self" : {
        "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/7908a89d-fc48-408f-ba23-846f8a08fbc5/shipping-methods/85036b51-215a-42df-acbf-1b8f30d506d5"
      }
    }
  } ],
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/7908a89d-fc48-408f-ba23-846f8a08fbc5"
    },
    "shipping-methods" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/7908a89d-fc48-408f-ba23-846f8a08fbc5/shipping-methods"
    }
  },
  "_id" : "7908a89d-fc48-408f-ba23-846f8a08fbc5"
}

Create shipping zone

A POST request is used to create a shipping zone.

Required scopes

shpz:c

Request body properties

Path Type Description

name

String

The name of the shipping zone.

serviceableCountries

Array

The list of countries this shipping zone applies to.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/shipping-zones' -i -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer <Access token>' -d '{
  "name" : "BE-NL-LU",
  "serviceableCountries" : [ "BE", "NL", "LU" ]
}'

Example response

HTTP/1.1 201 Created
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Location: https://api-shop.beyondshop.cloud/api/shipping-zones/bc89521a-85cc-410b-a0b3-3466610c718f
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 449

{
  "name" : "BE-NL-LU",
  "serviceableCountries" : [ "BE", "LU", "NL" ],
  "position" : 2,
  "shippingMethods" : [ ],
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/bc89521a-85cc-410b-a0b3-3466610c718f"
    },
    "shipping-methods" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/bc89521a-85cc-410b-a0b3-3466610c718f/shipping-methods"
    }
  },
  "_id" : "bc89521a-85cc-410b-a0b3-3466610c718f"
}

Update shipping zone

A PUT request is used to update a shipping zone.

Required scopes

shpz:u

Request body properties

Path Type Description

name

String

The name of the shipping zone.

serviceableCountries

Array

The list of countries this shipping zone applies to.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/shipping-zones/e9210124-67f9-4794-b46d-6d86ee78579b' -i -X PUT -H 'Content-Type: application/json' -H 'Authorization: Bearer <Access token>' -d '{
  "name" : "BENELUX region",
  "serviceableCountries" : [ "BE", "NL", "LU", "DE" ]
}'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1060

{
  "name" : "BENELUX region",
  "serviceableCountries" : [ "LU", "NL", "BE", "DE" ],
  "position" : 2,
  "shippingMethods" : [ {
    "name" : "Standard Shipping 2",
    "description" : "Standard Shipping",
    "taxClass" : "REGULAR",
    "position" : 0,
    "freeShippingValue" : {
      "currency" : "EUR",
      "amount" : 400
    },
    "fixedPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "weightBasedPrice" : null,
    "_id" : "f6d14a0f-428b-4305-8e1a-a0b6fb549d09",
    "_links" : {
      "self" : {
        "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/e9210124-67f9-4794-b46d-6d86ee78579b/shipping-methods/f6d14a0f-428b-4305-8e1a-a0b6fb549d09"
      }
    }
  } ],
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/e9210124-67f9-4794-b46d-6d86ee78579b"
    },
    "shipping-methods" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/e9210124-67f9-4794-b46d-6d86ee78579b/shipping-methods"
    }
  },
  "_id" : "e9210124-67f9-4794-b46d-6d86ee78579b"
}

Delete shipping zone

A DELETE request is used to delete a shipping zone. You cannot delete the shipping zone containing the last shipping method of a shop.

Required scopes

shpz:d

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/shipping-zones/b9a2d811-bd57-482b-ac63-ea0227376d73' -i -X DELETE -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

List shipping zones

A GET request will list all of the shipping zones in a paged manner.

Required scopes

shpz:r

Example request

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

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 2548

{
  "_embedded" : {
    "shipping-zones" : [ {
      "name" : "DE",
      "serviceableCountries" : [ "DE" ],
      "position" : 1,
      "shippingMethods" : [ {
        "name" : "Standard Shipping 1",
        "description" : "Standard Shipping",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : null,
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 16.95
        },
        "weightBasedPrice" : null,
        "_id" : "30984f9f-1af3-4868-8437-6675bb9988e1",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/32a7b31e-7b33-4e7d-a046-b25ae559223d/shipping-methods/30984f9f-1af3-4868-8437-6675bb9988e1"
          }
        }
      } ],
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/32a7b31e-7b33-4e7d-a046-b25ae559223d"
        },
        "shipping-methods" : {
          "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/32a7b31e-7b33-4e7d-a046-b25ae559223d/shipping-methods"
        }
      },
      "_id" : "32a7b31e-7b33-4e7d-a046-b25ae559223d"
    }, {
      "name" : "BE-NL-LU",
      "serviceableCountries" : [ "BE", "LU", "NL" ],
      "position" : 2,
      "shippingMethods" : [ {
        "name" : "Standard Shipping 2",
        "description" : "Standard Shipping",
        "taxClass" : "REGULAR",
        "position" : 0,
        "freeShippingValue" : {
          "currency" : "EUR",
          "amount" : 400
        },
        "fixedPrice" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 19.99
        },
        "weightBasedPrice" : null,
        "_id" : "1e5bf6ba-56c6-46b3-bfb7-fa3665ddd8ca",
        "_links" : {
          "self" : {
            "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/77826ea8-9c12-49f6-a53e-4187a4e23635/shipping-methods/1e5bf6ba-56c6-46b3-bfb7-fa3665ddd8ca"
          }
        }
      } ],
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/77826ea8-9c12-49f6-a53e-4187a4e23635"
        },
        "shipping-methods" : {
          "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/77826ea8-9c12-49f6-a53e-4187a4e23635/shipping-methods"
        }
      },
      "_id" : "77826ea8-9c12-49f6-a53e-4187a4e23635"
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 2,
    "totalPages" : 1,
    "number" : 0
  }
}

Sort shipping zones

Use a PUT request to sort the shipping zones. This is done by passing the self-links of the shipping zones in the desired order.

The request must contain uris for all shipping zones of the given page.

Required scopes

shpz:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/shipping-zones' -i -X PUT -H 'Content-Type: text/uri-list' -H 'Authorization: Bearer <Access token>' -d 'https://api-shop.beyondshop.cloud/api/shipping-zones/3ca2f30e-f7bf-420c-8db3-702ae54ce049
https://api-shop.beyondshop.cloud/api/shipping-zones/c3d86262-ded2-40cf-b21f-a7b1b19946e3
https://api-shop.beyondshop.cloud/api/shipping-zones/1055a34a-8b33-4df4-9923-2aeb15084e16'

Example response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Location: https://api-shop.beyondshop.cloud/api/shipping-zones

Show details of shipping method in shipping zone

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

Required scopes

shpz:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/shipping-zones/b9977338-2d7c-4f84-b0d1-c55b5ae87cd9/shipping-methods/81a1dbb0-7256-4a77-9e53-8b167283f119' -i -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_links

Object

See Hypermedia

_id

String

The immutable, unique identifier of the requested resource.

weightBasedPrice

Null

The price depending on the package weight.

fixedPrice

Object

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

position

Number

The sorting position of the shipping method in the merchant administration in relation to other shipping methods.

name

String

The name of the shipping method.

description

String

description

taxClass

String

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

freeShippingValue

Object

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

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 556

{
  "name" : "Standard Shipping 2",
  "description" : "Standard Shipping",
  "taxClass" : "REGULAR",
  "position" : 0,
  "freeShippingValue" : {
    "currency" : "EUR",
    "amount" : 400
  },
  "fixedPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 19.99
  },
  "weightBasedPrice" : null,
  "_id" : "81a1dbb0-7256-4a77-9e53-8b167283f119",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/b9977338-2d7c-4f84-b0d1-c55b5ae87cd9/shipping-methods/81a1dbb0-7256-4a77-9e53-8b167283f119"
    }
  }
}

Required scopes

shpz:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/shipping-zones/7bcbce92-fc9c-4fb3-85a9-7912b7a363f2/shipping-methods/a0a1de2e-a846-4590-8a16-fe4b1d1f5c7a' -i -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_links

Object

See Hypermedia

_id

String

The immutable, unique identifier of the requested resource.

weightBasedPrice

Null

The price depending on the package weight.

fixedPrice

Object

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

position

Number

The sorting position of the shipping method in the merchant administration in relation to other shipping methods.

name

String

The name of the shipping method.

description

String

description

taxClass

String

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

freeShippingValue

Null

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

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 512

{
  "name" : "Standard Shipping 1",
  "description" : "Standard Shipping",
  "taxClass" : "REGULAR",
  "position" : 0,
  "freeShippingValue" : null,
  "fixedPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 16.95
  },
  "weightBasedPrice" : null,
  "_id" : "a0a1de2e-a846-4590-8a16-fe4b1d1f5c7a",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/7bcbce92-fc9c-4fb3-85a9-7912b7a363f2/shipping-methods/a0a1de2e-a846-4590-8a16-fe4b1d1f5c7a"
    }
  }
}

Create shipping method in shipping zone

A POST request is used to create a shipping method in a shipping zone.

Required scopes

shpz:u

Request body properties

Path Type Description

name

String

The name of the shipping method.

description

String

description

taxClass

String

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

freeShippingValue

Object

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

fixedPrice

Object

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

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/shipping-zones/f8a25b73-bf45-413e-a9e5-b09a3909d56c/shipping-methods' -i -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer <Access token>' -d '{
  "name" : "Standard Shipping 2",
  "description" : "Standard Shipping",
  "taxClass" : "REGULAR",
  "freeShippingValue" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 400
  },
  "fixedPrice" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : "19.99"
  }
}'

Example response

HTTP/1.1 201 Created
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Location: https://api-shop.beyondshop.cloud/api/shipping-zones/f8a25b73-bf45-413e-a9e5-b09a3909d56c/shipping-methods/a0dc4090-279e-4d17-8dcf-b2d5c8b7d47a
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1580

{
  "name" : "DE",
  "serviceableCountries" : [ "DE" ],
  "position" : 1,
  "shippingMethods" : [ {
    "name" : "Standard Shipping 1",
    "description" : "Standard Shipping",
    "taxClass" : "REGULAR",
    "position" : 0,
    "freeShippingValue" : null,
    "fixedPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "weightBasedPrice" : null,
    "_id" : "2fc88cdc-a26e-48e4-a94b-8acc78386a51",
    "_links" : {
      "self" : {
        "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/f8a25b73-bf45-413e-a9e5-b09a3909d56c/shipping-methods/2fc88cdc-a26e-48e4-a94b-8acc78386a51"
      }
    }
  }, {
    "name" : "Standard Shipping 2",
    "description" : "Standard Shipping",
    "taxClass" : "REGULAR",
    "position" : 0,
    "freeShippingValue" : {
      "currency" : "EUR",
      "amount" : 400
    },
    "fixedPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 19.99
    },
    "weightBasedPrice" : null,
    "_id" : "a0dc4090-279e-4d17-8dcf-b2d5c8b7d47a",
    "_links" : {
      "self" : {
        "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/f8a25b73-bf45-413e-a9e5-b09a3909d56c/shipping-methods/a0dc4090-279e-4d17-8dcf-b2d5c8b7d47a"
      }
    }
  } ],
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/f8a25b73-bf45-413e-a9e5-b09a3909d56c"
    },
    "shipping-methods" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/f8a25b73-bf45-413e-a9e5-b09a3909d56c/shipping-methods"
    }
  },
  "_id" : "f8a25b73-bf45-413e-a9e5-b09a3909d56c"
}

Request body properties

Path Type Description

name

String

The name of the shipping method.

description

String

description

taxClass

String

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

freeShippingValue

Object

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

weightBasedPrice

Object

The price depending on the package weight.

weightBasedPrice.unlimitedWeightPrice

Object

The price for the package if its weight exceeds the highest weight threshold. If this value is not available, the shipping method is not applicable.

weightBasedPrice.weightPriceThresholds

Array

A list of package prices that are valid up to the respective maximum weight.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/shipping-zones/1a7b1f37-5eb6-46fb-809f-161a9c483dcd/shipping-methods' -i -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer <Access token>' -d '{
  "name" : "Standard Shipping 2",
  "description" : "Standard Shipping",
  "taxClass" : "REGULAR",
  "freeShippingValue" : {
    "taxModel" : "GROSS",
    "currency" : "EUR",
    "amount" : 400
  },
  "weightBasedPrice" : {
    "weightPriceThresholds" : [ {
      "maxWeight" : 1000,
      "price" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 4
      }
    }, {
      "maxWeight" : 5000,
      "price" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 9
      }
    } ],
    "unlimitedWeightPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 34
    }
  }
}'

Example response

HTTP/1.1 201 Created
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Location: https://api-shop.beyondshop.cloud/api/shipping-zones/1a7b1f37-5eb6-46fb-809f-161a9c483dcd/shipping-methods/4d7dae6c-25f9-4af2-bb65-36d1e54eab10
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1968

{
  "name" : "DE",
  "serviceableCountries" : [ "DE" ],
  "position" : 1,
  "shippingMethods" : [ {
    "name" : "Standard Shipping 1",
    "description" : "Standard Shipping",
    "taxClass" : "REGULAR",
    "position" : 0,
    "freeShippingValue" : null,
    "fixedPrice" : {
      "taxModel" : "GROSS",
      "currency" : "EUR",
      "amount" : 16.95
    },
    "weightBasedPrice" : null,
    "_id" : "4b075457-1b6f-451e-9437-192fafeb99ec",
    "_links" : {
      "self" : {
        "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/1a7b1f37-5eb6-46fb-809f-161a9c483dcd/shipping-methods/4b075457-1b6f-451e-9437-192fafeb99ec"
      }
    }
  }, {
    "name" : "Standard Shipping 2",
    "description" : "Standard Shipping",
    "taxClass" : "REGULAR",
    "position" : 0,
    "freeShippingValue" : {
      "currency" : "EUR",
      "amount" : 400
    },
    "fixedPrice" : null,
    "weightBasedPrice" : {
      "weightPriceThresholds" : [ {
        "maxWeight" : 1000,
        "price" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 4
        }
      }, {
        "maxWeight" : 5000,
        "price" : {
          "taxModel" : "GROSS",
          "currency" : "EUR",
          "amount" : 9
        }
      } ],
      "unlimitedWeightPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 34
      }
    },
    "_id" : "4d7dae6c-25f9-4af2-bb65-36d1e54eab10",
    "_links" : {
      "self" : {
        "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/1a7b1f37-5eb6-46fb-809f-161a9c483dcd/shipping-methods/4d7dae6c-25f9-4af2-bb65-36d1e54eab10"
      }
    }
  } ],
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/1a7b1f37-5eb6-46fb-809f-161a9c483dcd"
    },
    "shipping-methods" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/1a7b1f37-5eb6-46fb-809f-161a9c483dcd/shipping-methods"
    }
  },
  "_id" : "1a7b1f37-5eb6-46fb-809f-161a9c483dcd"
}

Delete shipping method in shipping zone

A DELETE request is used to delete a shipping method in a shipping zone. You cannot delete the last shipping method of a shop.

Required scopes

shpz:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/shipping-zones/64abd48d-3967-4c78-8c91-e50cd4573e78/shipping-methods/cb1ddca8-389f-457d-877e-a1a7c5ebca7f' -i -X DELETE -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 449

{
  "name" : "BE-NL-LU",
  "serviceableCountries" : [ "BE", "LU", "NL" ],
  "position" : 2,
  "shippingMethods" : [ ],
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/64abd48d-3967-4c78-8c91-e50cd4573e78"
    },
    "shipping-methods" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/64abd48d-3967-4c78-8c91-e50cd4573e78/shipping-methods"
    }
  },
  "_id" : "64abd48d-3967-4c78-8c91-e50cd4573e78"
}

List shipping methods of shipping zone

A GET request will list all of the shipping-methods of a shipping zonein a paged manner.

Required scopes

shpz:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/shipping-zones/d329121b-7451-4fc4-a157-f0d4275cd22e/shipping-methods' -i -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 847

{
  "_embedded" : {
    "shipping-methods" : [ {
      "name" : "Standard Shipping 2",
      "description" : "Standard Shipping",
      "taxClass" : "REGULAR",
      "position" : 0,
      "freeShippingValue" : {
        "currency" : "EUR",
        "amount" : 400
      },
      "fixedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 19.99
      },
      "weightBasedPrice" : null,
      "_id" : "30152b3c-767d-4e6b-a883-500ca1a73c09",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/d329121b-7451-4fc4-a157-f0d4275cd22e/shipping-methods/30152b3c-767d-4e6b-a883-500ca1a73c09"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/d329121b-7451-4fc4-a157-f0d4275cd22e/shipping-methods"
    }
  }
}

Sort shipping methods in shipping zone

Use a PUT request to sort the shipping methods inside a shipping zone. This is done by passing the self-links of the shipping methods in the desired order.

The request must contain uris for all shipping methods of this shipping zone.

Required scopes

shpz:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/shipping-zones/424b415f-18f7-49c7-8dbe-1832a9327728/shipping-methods' -i -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 3405

{
  "_embedded" : {
    "shipping-methods" : [ {
      "name" : "Standard Shipping 2-0",
      "description" : "Standard Shipping",
      "taxClass" : "REGULAR",
      "position" : 0,
      "freeShippingValue" : {
        "currency" : "EUR",
        "amount" : 400
      },
      "fixedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 2
      },
      "weightBasedPrice" : null,
      "_id" : "1c720924-b1e4-4949-8743-c7988ee79a6f",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/424b415f-18f7-49c7-8dbe-1832a9327728/shipping-methods/1c720924-b1e4-4949-8743-c7988ee79a6f"
        }
      }
    }, {
      "name" : "Standard Shipping 2-4",
      "description" : "Standard Shipping",
      "taxClass" : "REGULAR",
      "position" : 1,
      "freeShippingValue" : {
        "currency" : "EUR",
        "amount" : 400
      },
      "fixedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 2
      },
      "weightBasedPrice" : null,
      "_id" : "0a2b9698-6a3a-4cbc-9188-a6412343af6b",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/424b415f-18f7-49c7-8dbe-1832a9327728/shipping-methods/0a2b9698-6a3a-4cbc-9188-a6412343af6b"
        }
      }
    }, {
      "name" : "Standard Shipping 2-1",
      "description" : "Standard Shipping",
      "taxClass" : "REGULAR",
      "position" : 2,
      "freeShippingValue" : {
        "currency" : "EUR",
        "amount" : 400
      },
      "fixedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 2
      },
      "weightBasedPrice" : null,
      "_id" : "d10b1c26-2023-4404-a168-fa10be27992e",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/424b415f-18f7-49c7-8dbe-1832a9327728/shipping-methods/d10b1c26-2023-4404-a168-fa10be27992e"
        }
      }
    }, {
      "name" : "Standard Shipping 2-2",
      "description" : "Standard Shipping",
      "taxClass" : "REGULAR",
      "position" : 3,
      "freeShippingValue" : {
        "currency" : "EUR",
        "amount" : 400
      },
      "fixedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 2
      },
      "weightBasedPrice" : null,
      "_id" : "e4bf6e6a-f8c7-4555-afb1-2eb5ddb26780",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/424b415f-18f7-49c7-8dbe-1832a9327728/shipping-methods/e4bf6e6a-f8c7-4555-afb1-2eb5ddb26780"
        }
      }
    }, {
      "name" : "Standard Shipping 2-3",
      "description" : "Standard Shipping",
      "taxClass" : "REGULAR",
      "position" : 4,
      "freeShippingValue" : {
        "currency" : "EUR",
        "amount" : 400
      },
      "fixedPrice" : {
        "taxModel" : "GROSS",
        "currency" : "EUR",
        "amount" : 2
      },
      "weightBasedPrice" : null,
      "_id" : "65c8c81a-9fca-4f11-a7e7-3ea5d1edf418",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/424b415f-18f7-49c7-8dbe-1832a9327728/shipping-methods/65c8c81a-9fca-4f11-a7e7-3ea5d1edf418"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/424b415f-18f7-49c7-8dbe-1832a9327728/shipping-methods"
    }
  }
}

Find serviceable countries

Required scopes

shpz:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/shipping-zones/search/find-all-serviceable-countries' -i -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_embedded.countryCodes

Array

The list of country codes that products can be shipped to.

_links

Object

See Hypermedia

page

Object

See Pagination

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 428

{
  "_embedded" : {
    "countryCodes" : [ {
      "countryCode" : "DE"
    }, {
      "countryCode" : "BE"
    }, {
      "countryCode" : "LU"
    }, {
      "countryCode" : "NL"
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shipping-zones/search/find-all-serviceable-countries"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 4,
    "totalPages" : 1,
    "number" : 0
  }
}

Shop

List shop images

A GET request is used to retrieve the images of a shop.

Required scopes

shim:r

Example request

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

Response body properties

Path Type Description

_embedded

Object

List of images

_links

Object

See Hypermedia

page

Object

See Pagination

Links

Relation Description

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 941

{
  "_embedded" : {
    "images" : [ {
      "label" : "logo",
      "_id" : "29302dea-84c0-4ff7-a7d2-181150487840",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/shop/images/29302dea-84c0-4ff7-a7d2-181150487840"
        },
        "image" : {
          "href" : "https://api-shop.beyondshop.cloud/api/shop/images/29302dea-84c0-4ff7-a7d2-181150487840"
        },
        "data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/file.png?hash=212-2323-4343{&width,height,upscale}",
          "templated" : true
        },
        "metadata" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/file.png?hash=212-2323-4343&download=no"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shop/images?page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

Show shop image details

A GET request is used to retrieve a single image.

Required scopes

shim:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/shop/images/b44e7557-4dfe-4608-8a5f-52456d58915d' -i -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_id

String

The unique identifier of the image.

_links

Object

See Hypermedia

label

String

The label of the image that is used to state the purpose of the image. The labels 'logo' and 'fav-icon' can only be assigned once, and have a special meaning. The image with label 'logo' is used as the shop logo. The image with label 'fav-icon' is used as the fav icon of the shop.

Links

Relation Description

image

The absolute URI to the image.

data

The absolute URI to retrieve the binary image.

metadata

The absolute URI to retrieve the metadata of the image.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 615

{
  "label" : "logo",
  "_id" : "b44e7557-4dfe-4608-8a5f-52456d58915d",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shop/images/b44e7557-4dfe-4608-8a5f-52456d58915d"
    },
    "image" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shop/images/b44e7557-4dfe-4608-8a5f-52456d58915d"
    },
    "data" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/file.png?hash=212-2323-4343{&width,height,upscale}",
      "templated" : true
    },
    "metadata" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/file.png?hash=212-2323-4343&download=no"
    }
  }
}

Create shop image

A POST request is used to create an image.

Required scopes

shim:c

Request body properties

Path Type Description Constraints

dataUri

String

The encoded relative URI of the image.

Must be a valid storage service URI (must contain a hash query parameter). Must not be null

label

String

The label of the image that is used to state the purpose of the image. The labels 'logo' and 'fav-icon' can only be assigned once, and have a special meaning. The image with label 'logo' is used as the shop logo. The image with label 'fav-icon' is used as the fav icon of the shop.

Must not be empty

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/shop/images' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>' -d '{
  "dataUri" : "file.png?hash=212-2323-4343",
  "label" : "logo"
}'

Example response

HTTP/1.1 201 Created
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Location: https://api-shop.beyondshop.cloud/api/shop/images/97bfe003-24bb-47f2-965c-40c220d4d733

Delete shop image

A DELETE request is used to delete an image.

Required scopes

shim:d

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/shop/images/720dfc04-0184-4fc3-9334-0f01c867c505' -i -X DELETE -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Example response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

Find shop images by label

A GET request is issued to search images by label.

Required scopes

shim:r

Request parameters

Parameter Description

label

The label to find images for.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/shop/images/search/find-by-label?label=logo' -i -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

Object

List of images

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 962

{
  "_embedded" : {
    "images" : [ {
      "label" : "logo",
      "_id" : "88e1692f-6a85-45ba-b493-41519ec2fdcc",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/shop/images/88e1692f-6a85-45ba-b493-41519ec2fdcc"
        },
        "image" : {
          "href" : "https://api-shop.beyondshop.cloud/api/shop/images/88e1692f-6a85-45ba-b493-41519ec2fdcc"
        },
        "data" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/file.png?hash=212-2323-4343{&width,height,upscale}",
          "templated" : true
        },
        "metadata" : {
          "href" : "https://api-shop.beyondshop.cloud/api/api/core-storage/images/file.png?hash=212-2323-4343&download=no"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shop/images/search/find-by-label?page=0&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

A GET request is used to retrieve the legal content of a shop.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/legal-content' -i -H 'Content-Type: application/json' -H 'Accept: application/json'

Response body properties

Path Type Description

_embedded

Object

List of Legal Content excluding the content itself.

_links

Object

See Hypermedia

page

Object

See Pagination

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/json;charset=UTF-8
Content-Length: 2301

{
  "_embedded" : {
    "legal-content" : [ {
      "mandatory" : true,
      "type" : "terms-and-conditions",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/legal-content/terms-and-conditions"
        },
        "legal-content" : {
          "href" : "https://api-shop.beyondshop.cloud/api/legal-content/terms-and-conditions{?projection}",
          "templated" : true
        }
      }
    }, {
      "mandatory" : true,
      "type" : "legal-notice",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/legal-content/legal-notice"
        },
        "legal-content" : {
          "href" : "https://api-shop.beyondshop.cloud/api/legal-content/legal-notice{?projection}",
          "templated" : true
        }
      }
    }, {
      "mandatory" : true,
      "type" : "privacy-policy",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/legal-content/privacy-policy"
        },
        "legal-content" : {
          "href" : "https://api-shop.beyondshop.cloud/api/legal-content/privacy-policy{?projection}",
          "templated" : true
        }
      }
    }, {
      "mandatory" : true,
      "type" : "right-of-withdrawal",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/legal-content/right-of-withdrawal"
        },
        "legal-content" : {
          "href" : "https://api-shop.beyondshop.cloud/api/legal-content/right-of-withdrawal{?projection}",
          "templated" : true
        }
      }
    }, {
      "mandatory" : true,
      "type" : "shipping-information",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/legal-content/shipping-information"
        },
        "legal-content" : {
          "href" : "https://api-shop.beyondshop.cloud/api/legal-content/shipping-information{?projection}",
          "templated" : true
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/legal-content{?page,size,sort,projection}",
      "templated" : true
    },
    "profile" : {
      "href" : "https://api-shop.beyondshop.cloud/api/profile/legal-content"
    },
    "search" : {
      "href" : "https://api-shop.beyondshop.cloud/api/legal-content/search"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 5,
    "totalPages" : 1,
    "number" : 0
  }
}

A GET request is used to retrieve a single legal content.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/legal-content/right-of-withdrawal' -i -H 'Content-Type: application/json' -H 'Accept: application/json'

Response body properties

Path Type Description

_id

String

The unique identifier of the legal content.

type

String

The type of the legal content (cannot be changed).

content

String

The content the legal content page is supposed to show.

mandatory

Boolean

Indicates if legal content is necessary for the shop country (cannot be changed). Can be true or false.

_links

Object

See Hypermedia

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Last-Modified: Fri, 09 Feb 2018 14:27:38 GMT
ETag: "2"
Content-Type: application/json;charset=UTF-8
Content-Length: 500

{
  "type" : "right-of-withdrawal",
  "content" : "",
  "mandatory" : true,
  "_id" : "66d1cf9b-88b0-486b-b43c-db0412664278",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/legal-content/right-of-withdrawal"
    },
    "legal-content" : {
      "href" : "https://api-shop.beyondshop.cloud/api/legal-content/right-of-withdrawal{?projection}",
      "templated" : true
    },
    "pdf" : {
      "href" : "https://api-shop.beyondshop.cloud/api/api/pdf-storage/attachments/some.pdf?hash=23213"
    }
  }
}

A PUT request is used to update legal content. The only editable part is the content. Changes on type and mandatory will be ignored.

Required scopes

lcnt:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/legal-content/legal-notice' -i -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <Access token>' -d '{
  "type" : "legal-notice",
  "content" : "Here comes your legal notice!"
}'

Response body properties

Path Type Description

_id

String

The unique identifier of the legal content.

type

String

The type of the legal content (cannot be changed).

content

String

The content the legal content page is supposed to show.

mandatory

Boolean

Indicates if legal content is necessary for the shop country (cannot be changed). Can be true or false.

_links

Object

See Hypermedia

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
ETag: "2"
Last-Modified: Fri, 09 Feb 2018 14:27:39 GMT
Location: https://api-shop.beyondshop.cloud/api/legal-content/legal-notice
Content-Type: application/json;charset=UTF-8
Content-Length: 397

{
  "type" : "legal-notice",
  "content" : "Here comes your legal notice!",
  "mandatory" : true,
  "_id" : "8a895e8d-0d4b-4711-a6ca-f7ca54ff43f7",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/legal-content/legal-notice"
    },
    "legal-content" : {
      "href" : "https://api-shop.beyondshop.cloud/api/legal-content/legal-notice{?projection}",
      "templated" : true
    }
  }
}

The shop resources are used to manage shops.

Show shop details

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

Required scopes

shop:r

Example request

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

Response body properties

Path Type Description

_id

String

The unique identifier of the shop.

name

String

The name of the shop.

address

Object

The address of the shop.

address.company

Null

The company name related to the shop.

address.firstName

String

The first name of the shop owner.

address.lastName

String

The last name of the shop owner.

address.street

String

The street of the shop address.

address.street2

Null

Additional street field for the shop address.

address.city

String

The city of the shop address.

address.postalCode

String

The postal code of the shop address.

address.country

String

The country of the shop address.

address.state

String

The state of the shop address.

address.phone

Null

The phone number of the shop owner.

address.fax

Null

The fax number of the shop owner.

address.email

String

The email address of the shop owner.

address.vatId

Null

The VAT identifier of the shop.

address.commercialRegister

Null

The commercial register number for business customers.

defaultCurrency

String

The default currency of the shop.

currencies

Array

List of currencies that are supported by this shop. Defaults to defaultCurrency. The defaultCurrency is always included in this list.

defaultLocale

String

The default locale of the shop. Defaults to the locale of the corresponding site if not set.

locales

Array

List of locales that are supported by this shop. Defaults to defaultLocale. The defaultLocale is always included in this list.

taxModel

String

The tax model used for all product prices in this shop.

vatExempted

Boolean

Indicates if the merchant is exempted to declare VAT. Can be true or false.

closedByMerchant

Boolean

Indicates if the shop is closed by its owner. Can be true or false.

closedShopMessage

String

A message that is shown when the shop is closed by its owner.

listPriceText

Null

The text of the list price.

minimumOrderValue

Object

The minimum value a cart needs to have to be allowed to be purchased.

_links

Object

See Hypermedia

Links

Relation Description

shop

The link to the shop.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 929

{
  "name" : "myShop",
  "address" : {
    "company" : null,
    "firstName" : "Luke",
    "lastName" : "Skywalker",
    "email" : "some@me.de",
    "phone" : null,
    "fax" : null,
    "street" : "Somestreet 10",
    "street2" : null,
    "postalCode" : "12345",
    "city" : "Hamburg",
    "country" : "DE",
    "state" : "Tatooine",
    "vatId" : null,
    "commercialRegister" : null
  },
  "closedByMerchant" : true,
  "closedShopMessage" : "shop is currently closed for redesign",
  "currencies" : [ "EUR" ],
  "defaultCurrency" : "EUR",
  "locales" : [ "de-DE" ],
  "defaultLocale" : "de-DE",
  "vatExempted" : false,
  "taxModel" : "GROSS",
  "listPriceText" : null,
  "minimumOrderValue" : {
    "currency" : "EUR",
    "amount" : 29.99
  },
  "_id" : "27cb16a5-4d59-413f-9216-89970f2913ac",
  "_links" : {
    "shop" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shop{?projection}",
      "templated" : true
    }
  }
}

Show reduced view of shop details

A GET request is used to retrieve a reduced set of attributes of a shop.

Required scopes

shop:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/shop?projection=shopExcerptProjection' -i -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

name

String

The name of the shop.

closedByMerchant

Boolean

Indicates if the shop is closed by its owner. Can be true or false.

defaultCurrency

String

The default currency of the shop.

defaultLocale

String

The default locale of the shop. Defaults to the locale of the corresponding site if not set.

vatExempted

Boolean

Indicates if the merchant is exempted to declare VAT. Can be true or false.

taxModel

String

The tax model used for all product prices in this shop.

_links

Object

See Hypermedia

Links

Relation Description

shop

The link to the shop.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 286

{
  "closedByMerchant" : true,
  "defaultCurrency" : "EUR",
  "defaultLocale" : "de-DE",
  "vatExempted" : false,
  "taxModel" : "GROSS",
  "name" : "myShop",
  "_links" : {
    "shop" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shop{?projection}",
      "templated" : true
    }
  }
}

Show shop features

A GET request is used to retrieve the features of a shop.

Required scopes

shop:r

Example request

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

Response body properties

Path Type Description

features

Object

List of enabled features that are assigned to the shop.

features['core.auth.private-apps'].enabled

Boolean

Indicates if the feature is enabled. Can be true or false.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 167

{
  "features" : {
    "core.auth.private-apps" : {
      "enabled" : true
    },
    "marketing.google-shopping.product-export" : {
      "enabled" : true
    }
  }
}

Update shop

A PUT request is used to change attributes of a shop.

Required scopes

shop:u

Request body properties

Path Type Description Constraints

name

String

The name of the shop.

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

address

Object

The address of the shop.

Must not be null

address.company

Null

The company name related to the shop.

address.firstName

String

The first name of the shop owner.

address.lastName

String

The last name of the shop owner.

address.street

String

The street of the shop address.

address.street2

Null

Additional street field for the shop address.

address.city

String

The city of the shop address.

address.postalCode

String

The postal code of the shop address.

address.country

String

The country of the shop address.

address.state

String

The state of the shop address.

address.phone

Null

The phone number of the shop owner.

address.fax

Null

The fax number of the shop owner.

address.email

String

The email address of the shop owner.

address.vatId

Null

The VAT identifier of the shop.

address.commercialRegister

Null

The commercial register number for business customers.

defaultCurrency

String

The default currency of the shop.

Must not be null

currencies

Array

List of currencies that are supported by this shop. Defaults to defaultCurrency. The defaultCurrency is always included in this list.

defaultLocale

String

The default locale of the shop. Defaults to the locale of the corresponding site if not set.

locales

Array

List of locales that are supported by this shop. Defaults to defaultLocale. The defaultLocale is always included in this list.

taxModel

String

The tax model used for all product prices in this shop.

Must not be null

vatExempted

Boolean

Indicates if the merchant is exempted to declare VAT. Can be true or false.

closedByMerchant

Boolean

Indicates if the shop is closed by its owner. Can be true or false.

closedShopMessage

String

A message that is shown when the shop is closed by its owner.

Length must be between 0 and 65536 inclusive. Must be allowed markdown

listPriceText

Null

The text of the list price.

Length must be between 0 and 45 inclusive

minimumOrderValue

Object

The minimum value a cart needs to have to be allowed to be purchased.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/shop' -i -X PUT -H 'Content-Type: application/hal+json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>' -d '{
  "name" : "anotherName",
  "address" : {
    "company" : null,
    "firstName" : "Luke",
    "lastName" : "Skywalker",
    "email" : "some@me.de",
    "phone" : null,
    "fax" : null,
    "street" : "another street 1",
    "street2" : null,
    "postalCode" : "12345",
    "city" : "Hamburg",
    "country" : "DE",
    "state" : "Tatooine",
    "vatId" : null,
    "commercialRegister" : null
  },
  "closedByMerchant" : true,
  "closedShopMessage" : "shop is currently closed for redesign",
  "currencies" : [ "USD", "EUR" ],
  "defaultCurrency" : "USD",
  "locales" : [ "de-DE" ],
  "defaultLocale" : "de-DE",
  "vatExempted" : false,
  "taxModel" : "GROSS",
  "listPriceText" : null,
  "minimumOrderValue" : {
    "currency" : "USD",
    "amount" : 29.99
  }
}'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Location: https://api-shop.beyondshop.cloud/api/shop
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 944

{
  "name" : "anotherName",
  "address" : {
    "company" : null,
    "firstName" : "Luke",
    "lastName" : "Skywalker",
    "email" : "some@me.de",
    "phone" : null,
    "fax" : null,
    "street" : "another street 1",
    "street2" : null,
    "postalCode" : "12345",
    "city" : "Hamburg",
    "country" : "DE",
    "state" : "Tatooine",
    "vatId" : null,
    "commercialRegister" : null
  },
  "closedByMerchant" : true,
  "closedShopMessage" : "shop is currently closed for redesign",
  "currencies" : [ "USD", "EUR" ],
  "defaultCurrency" : "USD",
  "locales" : [ "de-DE" ],
  "defaultLocale" : "de-DE",
  "vatExempted" : false,
  "taxModel" : "GROSS",
  "listPriceText" : null,
  "minimumOrderValue" : {
    "currency" : "USD",
    "amount" : 29.99
  },
  "_id" : "dd4a37d7-222a-48d8-92a6-9832b474e5a6",
  "_links" : {
    "shop" : {
      "href" : "https://api-shop.beyondshop.cloud/api/shop{?projection}",
      "templated" : true
    }
  }
}

Users

List users

A GET request will list all of users visible to the current user.

Required scopes

user:r

Example request

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

Response body properties

Path Type Description

_embedded.users

Array

The list of users.

page

Object

See Pagination

_links

Object

See Hypermedia

Links

Relation Description

search

The endpoint to list all search endpoints.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 1125

{
  "_embedded" : {
    "users" : [ {
      "username" : "username",
      "email" : "baxter@example.org",
      "enabled" : true,
      "_id" : "358cbdd7-99d7-44c1-bc2a-011363bc7ddd",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/users/358cbdd7-99d7-44c1-bc2a-011363bc7ddd"
        },
        "user" : {
          "href" : "https://api-shop.beyondshop.cloud/api/users/358cbdd7-99d7-44c1-bc2a-011363bc7ddd"
        },
        "change-password" : {
          "href" : "https://api-shop.beyondshop.cloud/api/users/358cbdd7-99d7-44c1-bc2a-011363bc7ddd/change-password"
        },
        "roles" : {
          "href" : "https://api-shop.beyondshop.cloud/api/users/358cbdd7-99d7-44c1-bc2a-011363bc7ddd/roles"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/users{?page,size,sort}",
      "templated" : true
    },
    "profile" : {
      "href" : "https://api-shop.beyondshop.cloud/api/profile/users"
    },
    "search" : {
      "href" : "https://api-shop.beyondshop.cloud/api/users/search"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

Create user

A POST request is used to create a user.

Required scopes

user:c

Request body properties

Path Type Description Constraints

username

String

The username that identifies the user.

Must not be empty

email

String

The email address of the user account.

Must be a well-formed email address. Must not be null

password

String

The password of the user.

Must not be empty

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/users' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <Access token>' -d '{"username":"user","password":"password","email":"user@host.tld"}'

Response body properties

Path Type Description

username

String

The username that identifies the user.

email

String

The email address of the user account.

_id

String

The immutable, unique identifier of the requested resource.

enabled

Boolean

Indicates if the user is active. Can be true or false.

_links

Object

See Hypermedia

Example response

HTTP/1.1 201 Created
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
ETag: "1"
Last-Modified: Thu, 15 Feb 2018 13:38:28 GMT
Location: https://api-shop.beyondshop.cloud/api/users/03f7ba76-4519-4483-9e5e-240a292c97a7
Content-Type: application/json;charset=UTF-8
Content-Length: 605

{
  "username" : "user",
  "email" : "user@host.tld",
  "enabled" : true,
  "_id" : "03f7ba76-4519-4483-9e5e-240a292c97a7",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/users/03f7ba76-4519-4483-9e5e-240a292c97a7"
    },
    "user" : {
      "href" : "https://api-shop.beyondshop.cloud/api/users/03f7ba76-4519-4483-9e5e-240a292c97a7"
    },
    "change-password" : {
      "href" : "https://api-shop.beyondshop.cloud/api/users/03f7ba76-4519-4483-9e5e-240a292c97a7/change-password"
    },
    "roles" : {
      "href" : "https://api-shop.beyondshop.cloud/api/users/03f7ba76-4519-4483-9e5e-240a292c97a7/roles"
    }
  }
}

Show user details

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

Required scopes

user:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/users/6e2ffc67-3e8e-4e2a-bcee-d0cc7b1f0e28' -i -H 'Content-Type: application/json' -H 'Accept: application/hal+json' -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

username

String

The username that identifies the user.

email

String

The email address of the user account.

_id

String

The immutable, unique identifier of the requested resource.

enabled

Boolean

Indicates if the user is active. Can be true or false.

_links

Object

See Hypermedia

Links

Relation Description

user

The templated self link.

change-password

The link to the "Change password" endpoint.

roles

The roles of the user.

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Last-Modified: Thu, 15 Feb 2018 13:38:18 GMT
ETag: "1"
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 614

{
  "username" : "username",
  "email" : "baxter@example.org",
  "enabled" : true,
  "_id" : "6e2ffc67-3e8e-4e2a-bcee-d0cc7b1f0e28",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/users/6e2ffc67-3e8e-4e2a-bcee-d0cc7b1f0e28"
    },
    "user" : {
      "href" : "https://api-shop.beyondshop.cloud/api/users/6e2ffc67-3e8e-4e2a-bcee-d0cc7b1f0e28"
    },
    "change-password" : {
      "href" : "https://api-shop.beyondshop.cloud/api/users/6e2ffc67-3e8e-4e2a-bcee-d0cc7b1f0e28/change-password"
    },
    "roles" : {
      "href" : "https://api-shop.beyondshop.cloud/api/users/6e2ffc67-3e8e-4e2a-bcee-d0cc7b1f0e28/roles"
    }
  }
}

List user roles

A GET request will list all roles of a user.

Required scopes

user:r

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/users/324197c0-02fc-4779-8964-4b8f51ee815d/roles' -i -H 'Authorization: Bearer <Access token>'

Response body properties

Path Type Description

_embedded.roles

Array

The roles of the user.

_links

Object

See Hypermedia

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 629

{
  "_embedded" : {
    "roles" : [ {
      "generated" : false,
      "name" : "merchant",
      "_links" : {
        "self" : {
          "href" : "https://api-shop.beyondshop.cloud/api/roles/20a83bde-14c9-4dbe-b3ff-06789ac6517f"
        },
        "role" : {
          "href" : "https://api-shop.beyondshop.cloud/api/roles/20a83bde-14c9-4dbe-b3ff-06789ac6517f"
        },
        "scopes" : {
          "href" : "https://api-shop.beyondshop.cloud/api/roles/20a83bde-14c9-4dbe-b3ff-06789ac6517f/scopes"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/users/324197c0-02fc-4779-8964-4b8f51ee815d/roles"
    }
  }
}

Set user roles

A PUT request is used set the roles of a user.

Required scopes

user:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/users/a8430792-0e7d-4e30-a907-43499fdc6a4f/roles' -i -X PUT -H 'Content-Type: text/uri-list' -H 'Authorization: Bearer <Access token>' -d 'https://api-shop.beyondshop.cloud/api/roles/5f4c8c78-9b90-4cc5-a45d-88f54246a4fe'

Example response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

Add user roles

A POST request is used add the roles of a user.

Required scopes

user:r, user:u

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/users/a810a87b-24a6-43a2-9f79-1d12472264a9/roles' -i -X POST -H 'Content-Type: text/uri-list' -H 'Authorization: Bearer <Access token>' -d 'https://api-shop.beyondshop.cloud/api/roles/808456b8-b327-464b-a093-352324db572c'

Example response

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

Verify password

A POST request is used to verify a password against the password guidelines.

Request body properties

Path Type Description

password

String

The password that needs to be verified.

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/users/verify-password' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
  "password" : "ValidPassword!"
}'

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

Change password

A POST request is used to change the password of a user.

Request body properties

Path Type Description Constraints

currentPassword

String

The current password of the user. This is verified before the password change.

Must not be empty

newPassword

String

The new password to set in order to change the password.

Password must conform to the system password policy

Example request

$ curl 'https://api-shop.beyondshop.cloud/api/users/2469336b-1b5e-485f-932f-e577c2cad966/change-password' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <Access token>' -d '{"currentPassword":"password","newPassword":"ValidPassword123"}'

Response body properties

Path Type Description

username

String

The username that identifies the user.

email

String

The email address of the user account.

_id

String

The immutable, unique identifier of the requested resource.

enabled

Boolean

Indicates if the user is active. Can be true or false.

_links

Object

See Hypermedia

Example response

HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Type: application/json;charset=UTF-8
Content-Length: 610

{
  "username" : "user",
  "email" : "baxter@example.org",
  "enabled" : true,
  "_id" : "2469336b-1b5e-485f-932f-e577c2cad966",
  "_links" : {
    "self" : {
      "href" : "https://api-shop.beyondshop.cloud/api/users/2469336b-1b5e-485f-932f-e577c2cad966"
    },
    "user" : {
      "href" : "https://api-shop.beyondshop.cloud/api/users/2469336b-1b5e-485f-932f-e577c2cad966"
    },
    "change-password" : {
      "href" : "https://api-shop.beyondshop.cloud/api/users/2469336b-1b5e-485f-932f-e577c2cad966/change-password"
    },
    "roles" : {
      "href" : "https://api-shop.beyondshop.cloud/api/users/2469336b-1b5e-485f-932f-e577c2cad966/roles"
    }
  }
}

Trigger password reset

A POST request is used to trigger a password reset email to be sent to a user. The email will contain a link to the MBO’s password reset page. The link includes a JWT to authorize resetting it via the following endpoint.

Re