Recent Sales Orders

Overview

The Recent Sales Orders service is a mashup service that is used for retrieving the recent sales orders of a customer.

Using this service, you can retrieve a list of sales orders. All the sales orders are returned in descending order by the time of creation.

API Reference

/{tenant}/customers/{customerNumber}/recentItems

Overview of recent sales orders for a customer

/{tenant}/customers/{customerNumber}/recentItems

get

Retrieve a list of recent sales orders for the given customer.

The statuses that are treated to be closed: declined and completed

The statuses that are treated to be open: created, shipped and confirmed

Required scope: hybris.order_read

Retrieve a list of recent sales orders for the given customer.

The statuses that are treated to be closed: declined and completed

The statuses that are treated to be open: created, shipped and confirmed

Required scope: hybris.order_read

URI Parameters

  • tenant: required (string - minLength: 3 - maxLength: 16 - pattern: [a-z][a-z0-9]+)

    Stands for the "project" that requests this resource. Must match the "project" that is associated with the access token in the Authorization header.

    Example:

    myexampleshop
  • Customer Number: required (string)

    The customer ID

    Example:

    C0750876755

Headers

  • Authorization: required (string)

    Used to send a valid OAuth2 access token.

    Example:

    Bearer access_token

Query Parameters

  • openItemsMaxHits: (integer - default: 5)

    Maximum number of open sales orders to retrieve. The statuses that are treated to be Open is created, shipped and confirmed.

    Example:

    5
  • closedItemsMaxHits: (integer - default: 5)

    Maximum number closed sales orders to retrieve. The statuses that are treated to be Close is declined and completed.

    Example:

    5

HTTP status code 200

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Recent items GET response schema",
    "type": "object",
    "properties": {
        "numberOfOpenItems": {
            "type": "integer",
            "description": "Total number of open items"
        },
        "recentOpenItems": {
            "type": "array",
            "description": "Recent open items",
            "items": {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "title": "Recent item schema",
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "order number of the recent item as the index number"
                    },
                    "description": {
                        "type": "string",
                        "description": "The total price of the recent item"
                    },
                    "name": {
                        "type": "string",
                        "description": "order number of the recent item"
                    },
                    "modifiedAt": {
                        "type": "string",
                        "description": "Date and time the recent item was last changed at"
                    },
                    "statusDescription": {
                        "type": "string",
                        "description": "The statue of the recent item"
                    }
                }
            }
        },
        "numberOfClosedItems": {
            "type": "integer",
            "description": "Total number of closed items"
        },
        "recentClosedItems": {
            "type": "array",
            "description": "Recent closed items",
            "items": {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "title": "Recent item schema",
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "order number of the recent item as the index number"
                    },
                    "description": {
                        "type": "string",
                        "description": "The total price of the recent item"
                    },
                    "name": {
                        "type": "string",
                        "description": "order number of the recent item"
                    },
                    "modifiedAt": {
                        "type": "string",
                        "description": "Date and time the recent item was last changed at"
                    },
                    "statusDescription": {
                        "type": "string",
                        "description": "The statue of the recent item"
                    }
                }
            }
        }
    }
}

Example:

{
    "numberOfOpenItems": 3,
    "recentOpenItems": [
        {
            "id": "RV0KV1D6",
            "description": "USD 60",
            "name": "RV0KV1D6",
            "modifiedAt": "2015-06-26T03:43:27.716Z",
            "statusDescription": "CREATED"
        },
        {
            "id": "CL3Z90W9",
            "description": "USD 60",
            "name": "CL3Z90W9",
            "modifiedAt": "2015-06-15T08:04:34.695Z",
            "statusDescription": "CREATED"
        },
        {
            "id": "K3QFGVL3",
            "description": "USD 60",
            "name": "K3QFGVL3",
            "modifiedAt": "2015-06-15T07:35:18.965Z",
            "statusDescription": "CREATED"
        }
    ],
    "numberOfClosedItems": 1,
    "recentClosedItems": [
        {
            "id": "MKNN9VPV",
            "description": "USD 60",
            "name": "MKNN9VPV",
            "modifiedAt": "2015-06-15T06:31:47.718Z",
            "statusDescription": "COMPLETED"
        }
    ]
}

HTTP status code 204

HTTP status code 400

Body

Type: application/json

Schema:

error

Example:

{
    "status": 400,
    "type": "tenant_mismatch",
    "message": "Tenants in request header and resource path do not match"
}

HTTP status code 401

Given request is unauthorized. Bad or expired token. Reauthenticate the user. Any details will be provided within the response payload.

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "error",
    "description": "Schema for API specified errors.",
    "type": "object",
    "properties": {
        "status": {
            "type": "integer",
            "description": "original HTTP error code, should be consistent with the response HTTP code",
            "minimum": 100,
            "maximum": 599
        },
        "type": {
            "type": "string",
            "description": "classification of the error type, lower case with underscore eg validation_failure",
            "pattern": "[a-z]+[a-z_]*[a-z]+"
        },
        "message": {
            "type": "string",
            "description": "descriptive error message for debugging"
        },
        "moreInfo": {
            "type": "string",
            "format": "uri",
            "description": "link to documentation to investigate further and finding support"
        },
        "details": {
            "type": "array",
            "description": "list of problems causing this error",
            "items": {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "title": "errorDetail",
                "description": "schema for specific error cause",
                "type": "object",
                "properties": {
                    "field": {
                        "type": "string",
                        "description": "a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
                    },
                    "type": {
                        "type": "string",
                        "description": "classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
                        "pattern": "[a-z]+[a-z_]*[a-z]+"
                    },
                    "message": {
                        "type": "string",
                        "description": "descriptive error detail message for debugging"
                    },
                    "moreInfo": {
                        "type": "string",
                        "format": "uri",
                        "description": "link to documentation to investigate further and finding support for error detail"
                    }
                },
                "required": [
                    "type"
                ]
            }
        }
    },
    "required": [
        "status",
        "type"
    ]
}

Example:

{
    "status": 401,
    "message": "Authorization: Unauthorized. Bearer TOKEN is invalid",
    "type": "insufficient_credentials",
    "moreInfo": "https://api.yaas.io/patterns/errortypes.html"
}

HTTP status code 403

Evaluated request scopes in access token are not sufficient and do not match required scopes.

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "error",
    "description": "Schema for API specified errors.",
    "type": "object",
    "properties": {
        "status": {
            "type": "integer",
            "description": "original HTTP error code, should be consistent with the response HTTP code",
            "minimum": 100,
            "maximum": 599
        },
        "type": {
            "type": "string",
            "description": "classification of the error type, lower case with underscore eg validation_failure",
            "pattern": "[a-z]+[a-z_]*[a-z]+"
        },
        "message": {
            "type": "string",
            "description": "descriptive error message for debugging"
        },
        "moreInfo": {
            "type": "string",
            "format": "uri",
            "description": "link to documentation to investigate further and finding support"
        },
        "details": {
            "type": "array",
            "description": "list of problems causing this error",
            "items": {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "title": "errorDetail",
                "description": "schema for specific error cause",
                "type": "object",
                "properties": {
                    "field": {
                        "type": "string",
                        "description": "a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
                    },
                    "type": {
                        "type": "string",
                        "description": "classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
                        "pattern": "[a-z]+[a-z_]*[a-z]+"
                    },
                    "message": {
                        "type": "string",
                        "description": "descriptive error detail message for debugging"
                    },
                    "moreInfo": {
                        "type": "string",
                        "format": "uri",
                        "description": "link to documentation to investigate further and finding support for error detail"
                    }
                },
                "required": [
                    "type"
                ]
            }
        }
    },
    "required": [
        "status",
        "type"
    ]
}

Example:

{
    "status": 403,
    "message": "Given request does not have required scopes in access token. It is not authorized to perform this operation.",
    "type": "insufficient_permissions"
}

HTTP status code 500

Body

Type: application/json

Schema:

error

Example:

{
    "status": 500,
    "type": "internal_server_error",
    "message": "Internal server error"
}

Scopes

The table shows the scopes that the Recent Sales Order service supports.

SCOPEDESCRIPTION
hybris.order_readRead-only access to the Recent Sales Orders service

For more information about scopes, authorization, and authentication procedures for YaaS services, see Scopes and Authorization.

Manage Recent Sales Order

You can use the Recent Sales Orders service to retrieve recent sales orders for a specified customer. A valid order that a customer creates has these statuses: created, shipped, confirmed, declined, and completed.

  • created: the initial status of an order
  • confirmed: indicates that the seller received and accepted the order
  • shipped: indicates that the seller prepared and shipped the order
  • completed: indicates that the customer received the product
  • declined: indicates that the seller canceled the order

For more details about the meaning and transition of the statuses, see Order.

The Recent Sales Orders service returns the number and details of:

  • Recent open items consisting of orders with the statuses created, shipped, or confirmed
  • Recent closed items consisting of orders with the statuses declined or completed

To achieve better data retrieval performance, this service uses the data from the Engagement Center Indexing service.

Recent sales orders retrieval based on the customer number

You can retrieve a list of recent sales orders based on the customerNumber, using the GET method. To avoid overloading the client and hurting response times, use the query parameters openItemsMaxHits and closedItemsMaxHits. If you do not specify these parameters, they are set to the default value 5.

  • openItemsMaxHits sets the maximum length of the returned list recentOpenItems.
  • closedItemsMaxHits sets the maximum length of the returned list recentClosedItems. The response sorts the sales orders by the time of creation.

Retrieve Recent Sales Orders

Merchants can retrieve the details of the recent sales orders for a specified customer in a particular tenant. The request body does not need to contain any information. All the necessary data is in the query parameters and message headers. The recent sales orders are listed in descending order based on the time of creation.

This example shows how to retrieve recent sales orders by a customer number:

Request

  • Method: GET
  • RequestURL: https://api.beta.yaas.io/hybris/recent-order/v1/{tenant}/customers/{customerNumber}/recentItems
  • Headers
    • Authorization: This includes a valid OAuth2 access token. To access this method, the access token must be issued for the requested tenant and have the scope hybris.order_read
  • URI Parameter
    • {tenant}: The name of the current tenant
    • {customerNumber}: The unique identifier of the customer

Response

The successful response returns a 200 status code. An example JSON content including the recent sales orders looks similar to the following:

{
    "numberOfOpenItems": 3,
    "recentOpenItems": [
        {
            "id": "RV0KV1D6",
            "description": "USD 60",
            "name": " RV0KV1D6",
            "modifiedAt": "2015-06-26T03:43:27.716Z",
            "statusDescription": "CREATED"
        },
        {
            "id": "CL3Z90W9",
            "description": "USD 60",
            "name": " CL3Z90W9",
            "modifiedAt": "2015-06-15T08:04:34.695Z",
            "statusDescription": "CREATED"
        },
        {
            "id": "K3QFGVL3",
            "description": "USD 60",
            "name": " K3QFGVL3",
            "modifiedAt": "2015-06-15T07:35:18.965Z",
            "statusDescription": "CREATED"
        }
    ],
    "numberOfClosedItems": 1,
    "recentClosedItems": [
        {
            "id": "MKNN9VPV",
            "description": "USD 60",
            "name": " MKNN9VPV ",
            "modifiedAt": "2015-06-15T06:31:47.718Z",
            "statusDescription": "COMPLETED"
        }
    ]
}

Error Types

For information about error codes, see the API Reference.

  • Send feedback

    If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.

  • Get Help

    Use our private help channel. Receive updates over email and contact our specialists directly.

  • hybris Experts

    If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.