Search Bags

Search for all Bags placed through your application given certain filter critera.

Search Bags

post

Searches for bags matching the specified filter criteria. Supports filtering by bag ID, order ID, merchant ID, external ID, bag status, app order ID, and date ranges (created, submitted, last modified). Results are returned as a paginated VioletPage of Bag objects. When extended=true, app names are included in the response. By default, bags in IN_PROGRESS orders are excluded. Supports custom sorting via sort_by and sort_direction fields in the request body. Valid sort fields: id, dateLastModified, dateSubmitted, total, shippingTotal, subTotal, taxTotal.

Query parameters

pageinteger · int32Optional

Page number to retrieve, starting from 1

Default: 1Example: 1

sizeinteger · int32Optional

Number of bags per page (default 20)

Default: 20Example: 20

extendedbooleanOptional

When true, includes additional app name information in the response

Default: false

exclude_in_progressbooleanOptional

When true (default), excludes bags belonging to IN_PROGRESS orders

Default: true

Header parameters

X-Violet-TokenstringRequired

API token for authentication

X-Violet-App-SecretstringRequired

Application secret key

X-Violet-App-Idinteger · int32Required

Application ID

Example: 10000

Body

application/json

Bag Search Request

merchant_idinteger · int32Optional

Merchant ID

order_idinteger · int64Optional

Order ID

idinteger · int64Optional

Bag ID

external_idstringOptional

Bag External ID

bag_statusstring · enumOptional

Bag Status

Possible values:

app_order_idstringOptional

Order ID in the Channels System

before_datestring · date-timeOptionalDeprecated

Use date_last_modified:max.

after_datestring · date-timeOptionalDeprecated

Use date_last_modified:min.

before_date_createdstring · date-timeOptionalDeprecated

Use date_created:max.

after_date_createdstring · date-timeOptionalDeprecated

Use date_created:min.

sort_bystringOptional

Property to sort by in camelCase

sort_directionstringOptional

Direction to sort by

date_last_modified:minstring · date-timeOptional

Only include bags modified after this date.

Pattern: yyyy-MM-dd'T'HH:mm:ssZ

date_last_modified:maxstring · date-timeOptional

Only include bags modified before this date.

Pattern: yyyy-MM-dd'T'HH:mm:ssZ

date_created:minstring · date-timeOptional

Only include bags created after this date.

Pattern: yyyy-MM-dd'T'HH:mm:ssZ

date_created:maxstring · date-timeOptional

Only include bags created before this date.

Pattern: yyyy-MM-dd'T'HH:mm:ssZ

date_submitted:minstring · date-timeOptional

Only include bags submitted after this date.

Pattern: yyyy-MM-dd'T'HH:mm:ssZ

date_submitted:maxstring · date-timeOptional

Only include bags submitted before this date.

Pattern: yyyy-MM-dd'T'HH:mm:ssZ

Responses

200

success

application/json

lastbooleanOptional

Boolean indicating if this is the last page

total_pagesinteger · int32Optional

The total count of pages available

total_elementsinteger · int32Optional

The total count of objects available

firstbooleanOptional

Boolean indicating if this is the first page of the response

number_of_elementsinteger · int32Optional

The total number of objects in this specific response

sizeinteger · int32Optional

The page size selected at request time

numberinteger · int32Optional

The page number selected at request time

emptybooleanOptional

Boolean indicating if the response content is empty

next_page_cursorstringOptional

Contains the cursor for the next page. This property will only be used for situations where the API does not support the page number/page size paradigm and it will mutually exclusive with the size/number fields in the response. If this property is returned it must be passed when requesting the next page from the API. Does not apply to endpoints that do not have a next_page_cursor query param documented.

400

bad request

application/json

403

forbidden

application/json

500

internal server error

application/json

post

/orders/bags/search

HTTPcURLJavaScriptPython

POST /v1/orders/bags/search HTTP/1.1
Host: sandbox-api.violet.io
X-Violet-Token: text
X-Violet-App-Secret: text
X-Violet-App-Id: 1
Content-Type: application/json
Accept: */*
Content-Length: 25

{
  "bag_status": "ACCEPTED"
}

Find all accepted bagsFind bags for a specific merchantFind bags created within a date rangeFind a bag by its external platform ID

{
  "content": [
    {
      "id": 11111,
      "order_id": 10000,
      "merchant_id": 10000,
      "app_id": 10000,
      "status": "COMPLETED",
      "fulfillment_status": "FULFILLED",
      "financial_status": "PAID",
      "skus": [
        {
          "id": 10000,
          "merchant_id": 10000,
          "app_id": 10000,
          "sku_id": 99999,
          "external_id": "1234567890",
          "name": "Nintendo Entertainment System",
          "quantity": 2,
          "price": 9999,
          "line_price": 19998
        }
      ],
      "shipping_method": {
        "carrier": "USPS",
        "label": "Priority Mail",
        "price": 644
      },
      "sub_total": 19998,
      "shipping_total": 644,
      "tax_total": 2050,
      "discount_total": 0,
      "total": 22692,
      "date_created": "2024-06-28T20:31:56+0000",
      "date_last_modified": "2024-06-28T20:31:56+0000",
      "currency": "USD",
      "platform": "SHOPIFY",
      "bag_id": 11111,
      "bag_status": "COMPLETED",
      "merchant_name": "Legacy Games"
    }
  ],
  "last": false,
  "total_pages": 3,
  "total_elements": 47,
  "first": true,
  "number_of_elements": 20,
  "size": 20,
  "number": 1,
  "empty": false
}