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:

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

{
  "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 Claims

get

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

fields[Claim]stringOptional

The additional fields of the Claim to be returned.

Example: id,customer_id,claim_items

filterstringOptional

The RSQL filter of the Claim

supported fields:

• created_at_epoch (Epoch timestamp)

supported operators:

• >=
• <=
• >
• <
• ==
• !=
• =in=
• =out=

Example: created_at_epoch>=1746757960

page[size]integer · min: 1Optional

Number of records to return per page

Default: 10Example: 10

page[number]integer · min: 1Optional

Page number to return

Default: 1Example: 1

sortstringOptional

Comma-separated list of fields to sort by (prefix field with - for descending order)

Example: -created_at_epoch

Responses

200

Successful Response

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal Server Error

application/json

get

/ecommerce/claims/

HTTPcURLJavaScriptPython

GET /ecommerce/claims/ HTTP/1.1
Host: portal.public-api.services.yofi.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "jsonapi": {
    "version": "1.0"
  },
  "data": [
    {
      "id": "text",
      "type": "Claim",
      "attributes": {
        "id": "text",
        "shop_url": "text",
        "partner_id": "text",
        "organization_id": "text",
        "app_id": "text",
        "store_id": "text",
        "order_id": "text",
        "source_order_id": "text",
        "source_order_number": "text",
        "policy_id": "text",
        "claim_state": "text",
        "claim_type": "text",
        "external_source": "text",
        "author_name": "text",
        "author_email": "text",
        "customer_id": "text",
        "customer_phone": "text",
        "claim_description": "text",
        "is_ota": true,
        "ota_description": "text",
        "created_at": "text",
        "created_at_epoch": 1,
        "updated_at": "text",
        "deleted_at": "text",
        "claim_resolutions": {},
        "claim_items": {},
        "claim_messages": {},
        "metadata": {},
        "last_updated_at_yofi": "text",
        "last_updated_at_yofi_epoch": 1,
        "model_predictions": {}
      }
    }
  ],
  "meta": {
    "count": 1,
    "total_pages": 1,
    "total_count": 1,
    "page_number": 1,
    "page_size": 1
  }
}

Get Customers List

get

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

includestringOptional

The resources to be returned in included.

Example: customer_predictions

fields[EcommerceCustomer]stringOptional

The fields of the EcommerceCustomer to be returned.

Example: entity_id,customer_id,app_id,organization_id

fields[EcommerceCustomerPrediction]stringOptional

The fields of the EcommerceCustomerPrediction to be returned.

Example: severity,predicted_value,model_name,prediction_category,justification,prediction_title,is_result_prediction,customer_id,entity_id

filter[EcommerceCustomer]stringOptional

The RSQL filter of the EcommerceCustomer

supported fields:

• customer_id
• email

supported operators:

• ==
• !=

Example: email=='[email protected]'

page[size]integer · min: 1Optional

Number of records to return per page

Default: 10Example: 10

page[number]integer · min: 1Optional

Page number to return

Default: 1Example: 1

Responses

200

Successful Response

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal Server Error

application/json

get

/ecommerce/customers/

HTTPcURLJavaScriptPython

GET /ecommerce/customers/ HTTP/1.1
Host: portal.public-api.services.yofi.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "jsonapi": {
    "version": "1.0"
  },
  "data": [
    {
      "id": "text",
      "type": "EcommerceCustomer",
      "attributes": {
        "entity_id": "text",
        "customer_id": "text",
        "email": "text",
        "app_id": "text",
        "organization_id": "text",
        "analytics": {}
      }
    }
  ],
  "meta": {
    "count": 1,
    "total_pages": 1,
    "total_count": 1,
    "page_number": 1,
    "page_size": 1
  }
}

Get Customer Details

get

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

customer_idstringRequired

The ID of the customer

Example: 1234567890

Query parameters

includestringOptional

The resources to be returned in included.

Example: customer_predictions

fields[EcommerceCustomer]stringOptional

The fields of the EcommerceCustomer to be returned.

Example: entity_id,customer_id,app_id,organization_id

fields[EcommerceCustomerPrediction]stringOptional

The fields of the EcommerceCustomerPrediction to be returned.

Example: severity,predicted_value,model_name,prediction_category,justification,prediction_title,is_result_prediction,customer_id,entity_id

Responses

200

Successful Response

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal Server Error

application/json

get

/ecommerce/customers/{customer_id}/

HTTPcURLJavaScriptPython

GET /ecommerce/customers/{customer_id}/ HTTP/1.1
Host: portal.public-api.services.yofi.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "jsonapi": {
    "version": "1.0"
  },
  "data": {
    "id": "text",
    "type": "EcommerceCustomer",
    "attributes": {
      "entity_id": "text",
      "customer_id": "text",
      "email": "text",
      "app_id": "text",
      "organization_id": "text",
      "analytics": {}
    }
  }
}

Get Unified Returns

get

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

fields[EcommerceUnifiedReturn]stringOptional

The additional fields of the EcommerceUnifiedReturn to be returned.

Example: entity_id,app_id,order_id,customer_id,state,order_name,order_created_at_epoch,order_created_at_epoch,return_created_at_epoch,meta_data,return_total,customer_first_name,customer_last_name

filter[EcommerceUnifiedReturn]stringOptional

The RSQL filter of the EcommerceUnifiedReturn

supported fields:

• order_id
• customer_id
• order_number
• order_name
• state
• customer_first_name
• customer_last_name

supported operators:

• >=
• <=
• >
• <
• ==
• !=
• =in=
• =out=

Example: order_id=='test'

includestringOptional

The resources to be returned in included.

Example: customer,order,return_predictions,return_analytics,app

filter[EcommerceUnifiedReturnPrediction]stringOptional

The RSQL filter of the EcommerceUnifiedReturnPrediction

supported fields:

• prediction_category
• predicted_value

Example: (prediction_category==drop_off_fraud;predicted_value>0.9)

fields[EcommerceOrder]stringOptional

The additional fields of the EcommerceOrder to be returned.

Example: id,name,model_predictions

fields[EcommerceCustomer]stringOptional

The additional fields of the EcommerceCustomer to be returned.

Example: customer_id,first_name,last_name,model_predictions,email

page[size]integer · min: 1Optional

Number of records to return per page

Default: 10Example: 10

page[number]integer · min: 1Optional

Page number to return

Default: 1Example: 1

sortstringOptional

Comma-separated list of fields to sort by (prefix field with - for descending order)

Example: -order_created_at_epoch

Responses

200

Successful Response

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal Server Error

application/json

get

/unified_returns/

HTTPcURLJavaScriptPython

GET /unified_returns/ HTTP/1.1
Host: portal.public-api.services.yofi.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "jsonapi": {
    "version": "1.0"
  },
  "data": [
    {
      "id": "text",
      "type": "EcommerceUnifiedReturn",
      "attributes": {
        "entity_id": "text",
        "partner_id": "text",
        "organization_id": "text",
        "app_id": "text",
        "meta_data": {},
        "last_updated_at_yofi": "text",
        "last_updated_at_yofi_epoch": 1,
        "order_id": "text",
        "customer_id": "text",
        "created_at": "text",
        "updated_at": "text",
        "order_name": "text",
        "order_number": "text",
        "provider_order_number": "text",
        "provider_order_id": "text",
        "total": 1,
        "multi_currency": "text",
        "state": "text",
        "currency": "text",
        "exchange": "text",
        "exchange_order_name": "text",
        "exchange_order_id": "text",
        "gift_card_order_name": "text",
        "gift_card_order_id": "text",
        "gift_card": "text",
        "refund": 1,
        "refunds": {},
        "return_product_total": 1,
        "return_discount_total": 1,
        "return_tax_total": 1,
        "return_total": 1,
        "return_credit_total": 1,
        "handling_fee": 1,
        "exchange_product_total": 1,
        "exchange_discount_total": 1,
        "exchange_tax_total": 1,
        "exchange_total": 1,
        "exchange_credit_total": 1,
        "upsell": 1,
        "line_items": {},
        "customer_email": "text",
        "carrier": "text",
        "label_status": "text",
        "label_updated_at": "text",
        "label_url": "text",
        "label_rate": 1,
        "outcome": "text",
        "tracking_number": "text",
        "to_address_id": "text",
        "from_address_id": "text",
        "source_system": "text",
        "order_created_at_epoch": 1,
        "return_created_at_epoch": 1,
        "return_method": {},
        "return_method_provider": "text",
        "package_reference": "text",
        "shopify_refund_object": {},
        "customer_first_name": "text",
        "customer_last_name": "text",
        "type": "text",
        "labels": {}
      }
    }
  ],
  "meta": {
    "count": 1,
    "total_pages": 1,
    "total_count": 1,
    "page_number": 1,
    "page_size": 1
  }
}

Get Notification Events

get

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

fields[NotificationEvent]stringOptional

The additional fields of the NotificationEvent to be returned.

Example: id,notify_template_id,created_at

filterstringOptional

The RSQL filter of the NotificationEvent.

supported fields:

• created_at (ISO UTC datetime)

supported operators:

• >=
• <=
• >
• <
• ==
• !=
• =in=
• =out=

Example: created_at>=2025-06-06T11:54:41Z

page[size]integer · min: 1Optional

Number of records to return per page

Default: 10Example: 10

page[number]integer · min: 1Optional

Page number to return

Default: 1Example: 1

sortstringOptional

Comma-separated list of fields to sort by (prefix field with - for descending order)

Example: -created_at

Responses

200

Successful Response

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

Internal Server Error

application/json

get

/notification_events/

HTTPcURLJavaScriptPython

GET /notification_events/ HTTP/1.1
Host: portal.public-api.services.yofi.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "jsonapi": {
    "version": "1.0"
  },
  "data": [
    {
      "id": "text",
      "type": "NotificationEvent",
      "attributes": {
        "id": "text",
        "entity_id": "text",
        "entity_type": "text",
        "partner_id": "text",
        "app_id": "text",
        "organization_id": "text",
        "notification_source": "batch",
        "notification_target": [
          {
            "type": "email",
            "value": "text"
          }
        ],
        "notify_template_id": "text",
        "notification_payload": {},
        "sent_at": "2026-03-03T08:39:27.623Z",
        "created_at": "2026-03-03T08:39:27.623Z"
      }
    }
  ],
  "meta": {
    "count": 1,
    "total_pages": 1,
    "total_count": 1,
    "page_number": 1,
    "page_size": 1
  }
}