# Partner Data API

## Authentication

To send requests to this api,  you need to generate a JWT for authorization. The authorization in the HTTP header is a JWT token using `HS256` algorithm.

Please use the secret key(provided by Yofi) to generate a token. An example of **token claims** is shown below:

```json
{
  "iss": "partner_id/issuer", // Your partner id provided by Yofi
  "sub": "the-service-account-with-permissions", // Provided by Yofi
  "aud": ["yofi-public-api"], // Provided by Yofi
  "exp": 1716123456,   // Expiration Time
  "iat": 1716113456,   // The time at which the JWT was issued.
  "jti": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8", //uuid 
  "client_id": "backend-service", // Provided by Yofi
}
```

You also need to include the following headers in every request:

* `app_id``: "the-shopify-store.myshopify.com"` — The URL of Shopify store or your Yofi app ID
* `partner_id``: "shopify"` — The platform identifier within Yofi (currently fixed as `shopify`)

For partners who completed integration **prior to 2026**, please generate the JWT token using the payload specified herein. **No additional HTTP headers are required**.

```json
{
  "iss": "partner_id", // Partner ID
  "exp": 1716123456,   // Expiration Time
  "iat": 1716113456,   // The time at which the JWT was issued.
  "aud": "Yofi",       // Audience, case-sensitive
  "sub": "the-shopify-store.myshopify.com", // Shopify shop url, without https://
  "org_id": "the organization id"
}

```

## GET /ecommerce/claims/

> Get Claims

```json
{"openapi":"3.0.0","info":{"title":"Yofi Partner Data API","version":"0.2.4"},"servers":[{"url":"https://portal.public-api.services.yofi.ai","description":"API server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"claimFieldParam":{"name":"fields[Claim]","in":"query","required":false,"description":"The additional fields of the Claim to be returned.","schema":{"type":"string"}},"claimFilterParam":{"name":"filter","in":"query","required":false,"description":"The RSQL filter of the Claim\n\nsupported fields:\n\n  - created_at_epoch (Epoch timestamp)\n\nsupported operators:\n\n  - >=\n  - <=\n  - >\n  - <\n  - ==\n  - !=\n  - =in=\n  - =out=\n","schema":{"type":"string"}},"pageSizeParam":{"name":"page[size]","in":"query","required":false,"description":"Number of records to return per page","schema":{"type":"integer","minimum":1,"default":10}},"pageNumberParam":{"name":"page[number]","in":"query","required":false,"description":"Page number to return","schema":{"type":"integer","minimum":1,"default":1}}},"schemas":{"ClaimListResponse":{"type":"object","properties":{"jsonapi":{"type":"object","properties":{"version":{"type":"string","description":"JSON:API version"}}},"data":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"Claim":{"allOf":[{"$ref":"#/components/schemas/BaseResource"},{"type":"object","properties":{"type":{"type":"string","enum":["Claim"],"description":"Resource type"},"attributes":{"type":"object","description":"Claim-specific attributes","properties":{"id":{"type":"string","description":"Primary key identifier for the claim"},"shop_url":{"type":"string","description":"Primary key - shop URL associated with the claim"},"partner_id":{"type":"string","description":"Primary key - partner identifier for the claim"},"organization_id":{"type":"string","description":"Organization identifier"},"app_id":{"type":"string","description":"Application identifier"},"store_id":{"type":"string","description":"Store identifier"},"order_id":{"type":"string","description":"Order identifier"},"source_order_id":{"type":"string","description":"Source system order identifier"},"source_order_number":{"type":"string","description":"Source system order number"},"policy_id":{"type":"string","description":"Policy identifier"},"claim_state":{"type":"string","description":"Current state of the claim"},"claim_type":{"type":"string","description":"Type of claim"},"external_source":{"type":"string","description":"External source of the claim"},"author_name":{"type":"string","description":"Name of the claim author"},"author_email":{"type":"string","description":"Email of the claim author"},"customer_id":{"type":"string","description":"Customer identifier"},"customer_phone":{"type":"string","description":"Customer phone number"},"claim_description":{"type":"string","description":"Description of the claim"},"is_ota":{"type":"boolean","description":"Whether this is an OTA (over-the-air) claim"},"ota_description":{"type":"string","description":"Description for OTA claims"},"created_at":{"type":"string","description":"Creation timestamp"},"created_at_epoch":{"type":"integer","format":"int64","description":"Creation timestamp in epoch format"},"updated_at":{"type":"string","description":"Last update timestamp"},"deleted_at":{"type":"string","description":"Deletion timestamp (if applicable)"},"claim_resolutions":{"type":"object","description":"JSON data containing claim resolutions"},"claim_items":{"type":"object","description":"JSON data containing claim items"},"claim_messages":{"type":"object","description":"JSON data containing claim messages"},"metadata":{"type":"object","description":"Metadata associated with the claim"},"last_updated_at_yofi":{"type":"string","description":"Last update timestamp at Yofi"},"last_updated_at_yofi_epoch":{"type":"integer","format":"int64","description":"Last update timestamp at Yofi in epoch format"},"model_predictions":{"type":"object","description":"JSON data containing model predictions for the claim"}}}}}]},"BaseResource":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the resource"},"type":{"type":"string","description":"The type of the resource"},"attributes":{"type":"object","description":"Resource-specific attributes"}}},"PaginationMeta":{"type":"object","properties":{"count":{"type":"integer","description":"Number of items on the current page"},"total_pages":{"type":"integer","description":"Total number of pages"},"total_count":{"type":"integer","description":"Total number of items across all pages"},"page_number":{"type":"integer","description":"Current page number"},"page_size":{"type":"integer","description":"Number of items per page"}}},"JsonApiErrorResponse":{"type":"object","properties":{"jsonapi":{"type":"object","properties":{"version":{"type":"string","description":"JSON:API version"}}},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ResponseError"},"description":"Array of error objects"}},"required":["jsonapi","errors"]},"ResponseError":{"type":"object","properties":{"detail":{"type":"string","description":"The error message"},"status_code":{"type":"integer","description":"The status code"}}}},"responses":{"BadRequestError":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonApiErrorResponse"}}}},"UnauthorizedError":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonApiErrorResponse"}}}},"ForbiddenError":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonApiErrorResponse"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonApiErrorResponse"}}}}}},"paths":{"/ecommerce/claims/":{"get":{"summary":"Get Claims","operationId":"get_claims_ecommerce_claims__get","parameters":[{"$ref":"#/components/parameters/claimFieldParam"},{"$ref":"#/components/parameters/claimFilterParam"},{"$ref":"#/components/parameters/pageSizeParam"},{"$ref":"#/components/parameters/pageNumberParam"},{"name":"sort","in":"query","required":false,"description":"Comma-separated list of fields to sort by (prefix field with - for descending order)","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## GET /ecommerce/customers/

> Get Customers List

```json
{"openapi":"3.0.0","info":{"title":"Yofi Partner Data API","version":"0.2.4"},"servers":[{"url":"https://portal.public-api.services.yofi.ai","description":"API server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"customerIncludeParam":{"name":"include","in":"query","required":false,"description":"The resources to be returned in included.","schema":{"type":"string"}},"customerFieldParam":{"name":"fields[EcommerceCustomer]","in":"query","required":false,"description":"The fields of the EcommerceCustomer to be returned.","schema":{"type":"string"}},"customerPredictionFieldParam":{"name":"fields[EcommerceCustomerPrediction]","in":"query","required":false,"description":"The fields of the EcommerceCustomerPrediction to be returned.","schema":{"type":"string"}},"customerFilterParam":{"name":"filter[EcommerceCustomer]","in":"query","required":false,"description":"The RSQL filter of the EcommerceCustomer\n\nsupported fields:\n\n  - customer_id\n  - email\n\nsupported operators:\n\n  - ==\n  - !=\n","schema":{"type":"string"}},"pageSizeParam":{"name":"page[size]","in":"query","required":false,"description":"Number of records to return per page","schema":{"type":"integer","minimum":1,"default":10}},"pageNumberParam":{"name":"page[number]","in":"query","required":false,"description":"Page number to return","schema":{"type":"integer","minimum":1,"default":1}}},"schemas":{"CustomerListResponse":{"type":"object","properties":{"jsonapi":{"type":"object","properties":{"version":{"type":"string","description":"JSON:API version"}}},"data":{"type":"array","items":{"$ref":"#/components/schemas/EcommerceCustomer"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"EcommerceCustomer":{"allOf":[{"$ref":"#/components/schemas/BaseResource"},{"type":"object","properties":{"type":{"type":"string","enum":["EcommerceCustomer"],"description":"Resource type"},"attributes":{"type":"object","description":"Ecommerce customer-specific attributes","properties":{"entity_id":{"type":"string","description":"The ID of the customer"},"customer_id":{"type":"string","description":"The ID of the customer from Shopify"},"email":{"type":"string","description":"The email of the customer"},"app_id":{"type":"string","description":"The app ID"},"organization_id":{"type":"string","description":"The organization ID"},"analytics":{"type":"object","description":"The analytics of the customer"}}}}}]},"BaseResource":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the resource"},"type":{"type":"string","description":"The type of the resource"},"attributes":{"type":"object","description":"Resource-specific attributes"}}},"PaginationMeta":{"type":"object","properties":{"count":{"type":"integer","description":"Number of items on the current page"},"total_pages":{"type":"integer","description":"Total number of pages"},"total_count":{"type":"integer","description":"Total number of items across all pages"},"page_number":{"type":"integer","description":"Current page number"},"page_size":{"type":"integer","description":"Number of items per page"}}},"JsonApiErrorResponse":{"type":"object","properties":{"jsonapi":{"type":"object","properties":{"version":{"type":"string","description":"JSON:API version"}}},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ResponseError"},"description":"Array of error objects"}},"required":["jsonapi","errors"]},"ResponseError":{"type":"object","properties":{"detail":{"type":"string","description":"The error message"},"status_code":{"type":"integer","description":"The status code"}}}},"responses":{"BadRequestError":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonApiErrorResponse"}}}},"UnauthorizedError":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonApiErrorResponse"}}}},"ForbiddenError":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonApiErrorResponse"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonApiErrorResponse"}}}}}},"paths":{"/ecommerce/customers/":{"get":{"summary":"Get Customers List","operationId":"get_customers_list_ecommerce_customers__get","parameters":[{"$ref":"#/components/parameters/customerIncludeParam"},{"$ref":"#/components/parameters/customerFieldParam"},{"$ref":"#/components/parameters/customerPredictionFieldParam"},{"$ref":"#/components/parameters/customerFilterParam"},{"$ref":"#/components/parameters/pageSizeParam"},{"$ref":"#/components/parameters/pageNumberParam"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## GET /ecommerce/customers/{customer\_id}/

> Get Customer Details

```json
{"openapi":"3.0.0","info":{"title":"Yofi Partner Data API","version":"0.2.4"},"servers":[{"url":"https://portal.public-api.services.yofi.ai","description":"API server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"customerIdParam":{"name":"customer_id","in":"path","required":true,"description":"The ID of the customer","schema":{"type":"string"}},"customerIncludeParam":{"name":"include","in":"query","required":false,"description":"The resources to be returned in included.","schema":{"type":"string"}},"customerFieldParam":{"name":"fields[EcommerceCustomer]","in":"query","required":false,"description":"The fields of the EcommerceCustomer to be returned.","schema":{"type":"string"}},"customerPredictionFieldParam":{"name":"fields[EcommerceCustomerPrediction]","in":"query","required":false,"description":"The fields of the EcommerceCustomerPrediction to be returned.","schema":{"type":"string"}}},"schemas":{"CustomerDetailResponse":{"type":"object","properties":{"jsonapi":{"type":"object","properties":{"version":{"type":"string","description":"JSON:API version"}}},"data":{"$ref":"#/components/schemas/EcommerceCustomer"}}},"EcommerceCustomer":{"allOf":[{"$ref":"#/components/schemas/BaseResource"},{"type":"object","properties":{"type":{"type":"string","enum":["EcommerceCustomer"],"description":"Resource type"},"attributes":{"type":"object","description":"Ecommerce customer-specific attributes","properties":{"entity_id":{"type":"string","description":"The ID of the customer"},"customer_id":{"type":"string","description":"The ID of the customer from Shopify"},"email":{"type":"string","description":"The email of the customer"},"app_id":{"type":"string","description":"The app ID"},"organization_id":{"type":"string","description":"The organization ID"},"analytics":{"type":"object","description":"The analytics of the customer"}}}}}]},"BaseResource":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the resource"},"type":{"type":"string","description":"The type of the resource"},"attributes":{"type":"object","description":"Resource-specific attributes"}}},"JsonApiErrorResponse":{"type":"object","properties":{"jsonapi":{"type":"object","properties":{"version":{"type":"string","description":"JSON:API version"}}},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ResponseError"},"description":"Array of error objects"}},"required":["jsonapi","errors"]},"ResponseError":{"type":"object","properties":{"detail":{"type":"string","description":"The error message"},"status_code":{"type":"integer","description":"The status code"}}}},"responses":{"BadRequestError":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonApiErrorResponse"}}}},"UnauthorizedError":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonApiErrorResponse"}}}},"ForbiddenError":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonApiErrorResponse"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonApiErrorResponse"}}}}}},"paths":{"/ecommerce/customers/{customer_id}/":{"get":{"summary":"Get Customer Details","operationId":"get_customer_details_ecommerce_customers__customer_id__get","parameters":[{"$ref":"#/components/parameters/customerIdParam"},{"$ref":"#/components/parameters/customerIncludeParam"},{"$ref":"#/components/parameters/customerFieldParam"},{"$ref":"#/components/parameters/customerPredictionFieldParam"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerDetailResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## GET /unified\_returns/

> Get Unified Returns

```json
{"openapi":"3.0.0","info":{"title":"Yofi Partner Data API","version":"0.2.4"},"servers":[{"url":"https://portal.public-api.services.yofi.ai","description":"API server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"unifiedReturnFieldParam":{"name":"fields[EcommerceUnifiedReturn]","in":"query","required":false,"description":"The additional fields of the EcommerceUnifiedReturn to be returned.","schema":{"type":"string"}},"unifiedReturnFilterParam":{"name":"filter[EcommerceUnifiedReturn]","in":"query","required":false,"description":"The RSQL filter of the EcommerceUnifiedReturn\n\nsupported fields:\n\n  - order_id\n  - customer_id\n  - order_number\n  - order_name\n  - state\n  - customer_first_name\n  - customer_last_name\n\nsupported operators:\n\n  - >=\n  - <=\n  - >\n  - <\n  - ==\n  - !=\n  - =in=\n  - =out=\n","schema":{"type":"string"}},"unifiedReturnIncludeParam":{"name":"include","in":"query","required":false,"description":"The resources to be returned in included.","schema":{"type":"string"}},"unifiedReturnPredictionFilterParam":{"name":"filter[EcommerceUnifiedReturnPrediction]","in":"query","required":false,"description":"The RSQL filter of the EcommerceUnifiedReturnPrediction\n\nsupported fields:\n\n  - prediction_category\n  - predicted_value\n","schema":{"type":"string"}},"unifiedReturnOrderFieldParam":{"name":"fields[EcommerceOrder]","in":"query","required":false,"description":"The additional fields of the EcommerceOrder to be returned.","schema":{"type":"string"}},"unifiedReturnCustomerFieldParam":{"name":"fields[EcommerceCustomer]","in":"query","required":false,"description":"The additional fields of the EcommerceCustomer to be returned.","schema":{"type":"string"}},"pageSizeParam":{"name":"page[size]","in":"query","required":false,"description":"Number of records to return per page","schema":{"type":"integer","minimum":1,"default":10}},"pageNumberParam":{"name":"page[number]","in":"query","required":false,"description":"Page number to return","schema":{"type":"integer","minimum":1,"default":1}}},"schemas":{"EcommerceUnifiedReturnListResponse":{"type":"object","properties":{"jsonapi":{"type":"object","properties":{"version":{"type":"string","description":"JSON:API version"}}},"data":{"type":"array","items":{"$ref":"#/components/schemas/EcommerceUnifiedReturn"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"EcommerceUnifiedReturn":{"allOf":[{"$ref":"#/components/schemas/BaseResource"},{"type":"object","properties":{"type":{"type":"string","enum":["EcommerceUnifiedReturn"],"description":"Resource type"},"attributes":{"type":"object","description":"Order return-specific attributes","properties":{"entity_id":{"type":"string","description":"Unique identifier for the return"},"partner_id":{"type":"string","description":"Partner identifier"},"organization_id":{"type":"string","description":"Organization identifier"},"app_id":{"type":"string","description":"Application identifier"},"meta_data":{"type":"object","description":"Additional metadata for the return"},"last_updated_at_yofi":{"type":"string","description":"Timestamp of last update at Yofi"},"last_updated_at_yofi_epoch":{"type":"integer","description":"Epoch timestamp of last update at Yofi"},"order_id":{"type":"string","description":"Order identifier"},"customer_id":{"type":"string","description":"Customer identifier"},"created_at":{"type":"string","description":"Creation timestamp"},"updated_at":{"type":"string","description":"Update timestamp"},"order_name":{"type":"string","description":"Name of the order"},"order_number":{"type":"string","description":"Order number"},"provider_order_number":{"type":"string","description":"Provider's order number"},"provider_order_id":{"type":"string","description":"Provider's order ID"},"total":{"type":"number","format":"float","description":"Total amount"},"multi_currency":{"type":"string","description":"Multi-currency information"},"state":{"type":"string","description":"Current state of the return"},"currency":{"type":"string","description":"Currency code"},"exchange":{"type":"string","description":"Exchange information"},"exchange_order_name":{"type":"string","description":"Exchange order name"},"exchange_order_id":{"type":"string","description":"Exchange order ID"},"gift_card_order_name":{"type":"string","description":"Gift card order name"},"gift_card_order_id":{"type":"string","description":"Gift card order ID"},"gift_card":{"type":"string","description":"Gift card information"},"refund":{"type":"number","format":"float","description":"Refund amount"},"refunds":{"type":"object","description":"Detailed refunds information"},"return_product_total":{"type":"number","format":"float","description":"Total of returned products"},"return_discount_total":{"type":"number","format":"float","description":"Total discounts on returns"},"return_tax_total":{"type":"number","format":"float","description":"Total tax on returns"},"return_total":{"type":"number","format":"float","description":"Total return amount"},"return_credit_total":{"type":"number","format":"float","description":"Total credit amount for returns"},"handling_fee":{"type":"number","format":"float","description":"Handling fee"},"exchange_product_total":{"type":"number","format":"float","description":"Total of exchange products"},"exchange_discount_total":{"type":"number","format":"float","description":"Total discounts on exchanges"},"exchange_tax_total":{"type":"number","format":"float","description":"Total tax on exchanges"},"exchange_total":{"type":"number","format":"float","description":"Total exchange amount"},"exchange_credit_total":{"type":"number","format":"float","description":"Total credit amount for exchanges"},"upsell":{"type":"number","format":"float","description":"Upsell amount"},"line_items":{"type":"object","description":"Line items in the return"},"customer_email":{"type":"string","description":"Customer email address"},"carrier":{"type":"string","description":"Shipping carrier"},"label_status":{"type":"string","description":"Status of the shipping label"},"label_updated_at":{"type":"string","description":"Label update timestamp"},"label_url":{"type":"string","description":"URL for the shipping label"},"label_rate":{"type":"number","format":"float","description":"Label rate"},"outcome":{"type":"string","description":"Return outcome"},"tracking_number":{"type":"string","description":"Tracking number"},"to_address_id":{"type":"string","description":"Destination address ID"},"from_address_id":{"type":"string","description":"Source address ID"},"source_system":{"type":"string","description":"Source system"},"order_created_at_epoch":{"type":"integer","description":"Epoch timestamp when the order was created"},"return_created_at_epoch":{"type":"integer","description":"Epoch timestamp when the return was created"},"return_method":{"type":"object","description":"Return method details"},"return_method_provider":{"type":"string","description":"Provider of the return method"},"package_reference":{"type":"string","description":"Package reference"},"shopify_refund_object":{"type":"object","description":"Shopify refund object"},"customer_first_name":{"type":"string","description":"Customer's first name"},"customer_last_name":{"type":"string","description":"Customer's last name"},"type":{"type":"string","description":"Return type"},"labels":{"type":"object","description":"Labels information"}}}}}]},"BaseResource":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the resource"},"type":{"type":"string","description":"The type of the resource"},"attributes":{"type":"object","description":"Resource-specific attributes"}}},"PaginationMeta":{"type":"object","properties":{"count":{"type":"integer","description":"Number of items on the current page"},"total_pages":{"type":"integer","description":"Total number of pages"},"total_count":{"type":"integer","description":"Total number of items across all pages"},"page_number":{"type":"integer","description":"Current page number"},"page_size":{"type":"integer","description":"Number of items per page"}}},"JsonApiErrorResponse":{"type":"object","properties":{"jsonapi":{"type":"object","properties":{"version":{"type":"string","description":"JSON:API version"}}},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ResponseError"},"description":"Array of error objects"}},"required":["jsonapi","errors"]},"ResponseError":{"type":"object","properties":{"detail":{"type":"string","description":"The error message"},"status_code":{"type":"integer","description":"The status code"}}}},"responses":{"BadRequestError":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonApiErrorResponse"}}}},"UnauthorizedError":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonApiErrorResponse"}}}},"ForbiddenError":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonApiErrorResponse"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonApiErrorResponse"}}}}}},"paths":{"/unified_returns/":{"get":{"summary":"Get Unified Returns","operationId":"get_unified_returns_unified_returns__get","parameters":[{"$ref":"#/components/parameters/unifiedReturnFieldParam"},{"$ref":"#/components/parameters/unifiedReturnFilterParam"},{"$ref":"#/components/parameters/unifiedReturnIncludeParam"},{"$ref":"#/components/parameters/unifiedReturnPredictionFilterParam"},{"$ref":"#/components/parameters/unifiedReturnOrderFieldParam"},{"$ref":"#/components/parameters/unifiedReturnCustomerFieldParam"},{"$ref":"#/components/parameters/pageSizeParam"},{"$ref":"#/components/parameters/pageNumberParam"},{"name":"sort","in":"query","required":false,"description":"Comma-separated list of fields to sort by (prefix field with - for descending order)","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EcommerceUnifiedReturnListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## GET /notification\_events/

> Get Notification Events

```json
{"openapi":"3.0.0","info":{"title":"Yofi Partner Data API","version":"0.2.4"},"servers":[{"url":"https://portal.public-api.services.yofi.ai","description":"API server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"notificationEventFieldParam":{"name":"fields[NotificationEvent]","in":"query","required":false,"description":"The additional fields of the NotificationEvent to be returned.","schema":{"type":"string"}},"notificationEventFilterParam":{"name":"filter","in":"query","required":false,"description":"The RSQL filter of the NotificationEvent.\n\nsupported fields:\n  - created_at (ISO UTC datetime)\n\nsupported operators:\n\n  - >=\n  - <=\n  - >\n  - <\n  - ==\n  - !=\n  - =in=\n  - =out=\n","schema":{"type":"string"}},"pageSizeParam":{"name":"page[size]","in":"query","required":false,"description":"Number of records to return per page","schema":{"type":"integer","minimum":1,"default":10}},"pageNumberParam":{"name":"page[number]","in":"query","required":false,"description":"Page number to return","schema":{"type":"integer","minimum":1,"default":1}},"sortParam":{"name":"sort","in":"query","required":false,"description":"Comma-separated list of fields to sort by (prefix field with - for descending order)","schema":{"type":"string"}}},"schemas":{"NotificationEventListResponse":{"type":"object","properties":{"jsonapi":{"type":"object","properties":{"version":{"type":"string","description":"JSON:API version"}}},"data":{"type":"array","items":{"$ref":"#/components/schemas/NotificationEvent"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}},"NotificationEvent":{"allOf":[{"$ref":"#/components/schemas/BaseResource"},{"type":"object","properties":{"type":{"type":"string","enum":["NotificationEvent"],"description":"Resource type"},"attributes":{"type":"object","description":"Notification event-specific attributes","properties":{"id":{"type":"string","description":"Unique identifier for the notification event (hash of fields)"},"entity_id":{"type":"string","description":"ID of the entity this notification is about"},"entity_type":{"type":"string","description":"Type of entity (e.g., order, customer, return, claim, card, confirmation_code)"},"partner_id":{"type":"string","description":"Partner identifier (e.g., shopify, retail, redo, order_protection)"},"app_id":{"type":"string","description":"Application identifier (e.g., jdsports-ca.myshopify.com)"},"organization_id":{"type":"string","description":"Organization identifier"},"notification_source":{"type":"string","enum":["batch","preview","stream"],"description":"Source of the notification"},"notification_target":{"type":"array","description":"Array of notification target configurations","items":{"type":"object","properties":{"type":{"type":"string","enum":["email","slack","api"],"description":"Type of notification target"},"value":{"type":"string","description":"Target value (e.g., email addresses, slack channel)"}}}},"notify_template_id":{"type":"string","description":"Template identifier for the notification"},"notification_payload":{"type":"object","description":"Payload data for the notification"},"sent_at":{"type":"string","format":"date-time","description":"Timestamp when notification was sent"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when notification event was created"}}}}}]},"BaseResource":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the resource"},"type":{"type":"string","description":"The type of the resource"},"attributes":{"type":"object","description":"Resource-specific attributes"}}},"PaginationMeta":{"type":"object","properties":{"count":{"type":"integer","description":"Number of items on the current page"},"total_pages":{"type":"integer","description":"Total number of pages"},"total_count":{"type":"integer","description":"Total number of items across all pages"},"page_number":{"type":"integer","description":"Current page number"},"page_size":{"type":"integer","description":"Number of items per page"}}},"JsonApiErrorResponse":{"type":"object","properties":{"jsonapi":{"type":"object","properties":{"version":{"type":"string","description":"JSON:API version"}}},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ResponseError"},"description":"Array of error objects"}},"required":["jsonapi","errors"]},"ResponseError":{"type":"object","properties":{"detail":{"type":"string","description":"The error message"},"status_code":{"type":"integer","description":"The status code"}}}},"responses":{"BadRequestError":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonApiErrorResponse"}}}},"UnauthorizedError":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonApiErrorResponse"}}}},"ForbiddenError":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonApiErrorResponse"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonApiErrorResponse"}}}}}},"paths":{"/notification_events/":{"get":{"summary":"Get Notification Events","operationId":"get_notification_events_notification_events__get","parameters":[{"$ref":"#/components/parameters/notificationEventFieldParam"},{"$ref":"#/components/parameters/notificationEventFilterParam"},{"$ref":"#/components/parameters/pageSizeParam"},{"$ref":"#/components/parameters/pageNumberParam"},{"$ref":"#/components/parameters/sortParam"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationEventListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.yofi.ai/yofi-on-shopify/partner-service-integration/partner-data-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.