Exporting Offers CSV

This topic provides developers with step-by-step instructions for exporting product pricing data in CSV format using Offers export API endpoints. It includes initiating an export request and downloading a CSV file containing product prices, enabling seamless integration with pricing analytics, inventory management, or external reporting tools.

Exporting product pricing data as a CSV file involves three main steps:

1. Initiate an export request: Send a request to generate an exportId and configure filters to target specific data.
2. Retrieve the export details: Use the exportId to check the progress and retrieve the fileId after the export is complete.
3. Download the CSV File: With the fileId, obtain a download link to retrieve the CSV file.

Export parameters

You can the refine the data included in your export by specifying filters in the filters array. If you leave the array empty, all data is included. The following table describes the parameters for filtering and the functions of each parameter:

Parameter	Description
field	Specifies the data type used to search. Use priceType to set it as the search criteria.
value	Specifies the exact value for the selected field. If priceType is used as field, you must enter the corresponding priceType value for this parameter.
operator	Specifies how the value is applied to the field. If the field is priceType and the operator is set to EQUAL, all products with the specified value are included in the search result.

The following table provides detailed information for the two different data types:

• CALCULATED_PRICE: If the data type you want to export is CALCULATED_PRICE, use the following field, operator, and value:

  field	operator	value
  priceType	EQUAL	Filter your data by BASE or SALE price. If the filters array in the request body is empty, both prices are included in the CSV export.
  priceListIds	IN	Filter your data by a list of priceListIds by including them in an array in the request body. If the filters array is empty, the data is based on the default priceList.
  calculationTime	EQUAL	Filter your data by an ISO timestamp to specify when the price should be calculated. The provided timestamp is used for price determination. If the filters array is empty, the price is based on the CSV execution time.

• REDEMPTION: If the data type you want to export is REDEMPTION, use the following field, operator, and value:

  field	operator	value
  promoCode	EQUAL	Filter your data by redeemed promotion code.
  userId	EQUAL	Filter your data by provided user ID.
  email	EQUAL	Filter your data by provided email.
  orderId	EQUAL	Filter your data by provided order ID.
  redeemedAt	EQUAL GREATER_THAN_OR_EQUAL_TO LESS_THAN	Filter data based on the provided redemption date. If the operator is: EQUAL: Redemptions on the provided date. GREATER_THAN_OR_EQUAL_TO: Redemptions on and after the provided date. LESS_THAN: Redemptions before the provided date.
  storeId	EQUAL	Filter data based on case-insensitive promotion titles.
  promotionStatus	EQUAL	Filter data based on the specified promotion status: ACTIVE EXPIRED DISABLED

  We recommend not to seach for all the REDEMPTION data by leaving the filters array empty.

Prerequisites

• Ensure that you have Offers editor or administrator privileges to fabric Offers. For more information, see the Role-Based Access Control section.
• Ensure that you have added one or more products using one of the following methods:
  • Copilot
  • API endpoints
• Ensure that you have added price to the products using one of the following methods:
  • Copilot
  • API endpoints
• Ensure that you have created a redemption for the products using the create a redemption endpoint.

Procedure

Step 1: Initiating an export request

1. Submit a POST request including the type, such as CALCULATED_PRICE or REDEMPTION with any required filters. The duration for this process increases with the amount of data being exported. The initiate offers export endpoint initiates a CSV export request and generates an exportId. The following example shows a POST request with the request body set to type as REDEMPTION, searching for storeId with the value store001:

   Click here to expand and see the request payload.

   curl --request POST \
   --url https://live.copilot.fabric.inc/api-offers/offers-exports \
   --header 'Authorization: Bearer exampleToken123' \
   --header 'Content-Type: application/json' \
   --header 'x-fabric-tenant-id: exampleTenantID456' \
   --data '{
   "type": "REDEMPTION",
   "filters": [
           {
           "field": "storeId",
           "value": "store001",
           "operator": "EQUAL"
           }
       ]
   }'
   

   A successful request returns the following response:

   Click here to expand and see the response.

   {
   "exportId": "ab50fe48-5da0-4e77-92d1-bb629eedf19e",
   "startedAt": "2023-05-17T21:24:52.398Z",
   "endedAt": "null",
   "totalDataExported": 0,
   "status": "IN_PROGRESS",
   "errors": [],
   "type": "REDEMPTION",
   "filters": [
       {
       "field": "storeId",
       "value": "store001",
       "operator": "EQUAL"
       }
   ]
   }
   

Step 2: Retrieve the fileId

After initiating the export request, use the exportId generated in step 1 to retrieve details of the request. You can view the export details, such as startedAt and endedAt times, as well as the totalDataExported. The export request might take up to 10 hours.

1.Submit a GET request using the exportId endpoint to check the export status to retrieve the fileId.

1. When the status is COMPLETE, use the fileId in the download the exported CSV file step to download the CSV file.

Use the following GET request to retrieve the details of an export request, including its status and fileId:

Click here to expand and see the request payload.

curl --request GET \
--url https://live.copilot.fabric.inc/api-offers/offers-exports/ab50fe48-5da0-4e77-92d1-bb629eedf19e \
--header 'Authorization: Bearer exampleToken123' \
--header 'x-fabric-tenant-id: exampleTenantID456'

A successful request returns the following response:

Click here to expand and see the response.

{
"exportId": "ab50fe48-5da0-4e77-92d1-bb629eedf19e",
"startedAt": "2023-05-17T21:24:52.398Z",
"endedAt": "null",
"totalDataExported": 0,
"status": "IN_PROGRESS",
"errors": [],
"type": "REDEMPTION",
"filters": [
    {
    "field": "storeId",
    "value": "store001",
    "operator": "EQUAL"
    }
],
"fileId": "redemption/tenantId/1687472977242-redemption-export.csv"
}

Wait until you receive a response with status: COMPLETED before moving to the next step. If you don’t receive a status of COMPLETED, you won’t get a complete export file.

Step 3: Downloading the exported CSV file

1. After retrieving fileId from step 2, include it in the request body of the download exported CSV file endpoint to generate a temporary URL for downloading the file as shown in the following request:

   Click here to expand and see the request payload.

   curl --request POST \
   --url https://live.copilot.fabric.inc/api-offers/offers-exports/actions/download-export-file \
   --header 'Authorization: Bearer exampleToken123' \
   --header 'Content-Type: application/json' \
   --header 'x-fabric-tenant-id: exampleTenantID456' \
   --data '{
   "fileId": "redemption/tenantId/1687472972-redemption-export.csv"
   }'
   

   A successful request returns the following response with a URL used to download your file:

   Click here to expand and see the response.

   {
   "url": {Your Download URL},
   "fileId": "redemption/tenantId/1687472972-redemption-export.csv"
   }
   

   You can copy and paste the URL from the response into your browser’s address bar to download your file.

This URL is valid for 5 minutes. If you exceeded this duration, repeat step 3 to generate another URL.

Common Variations

Searching with multiple fields

You can include more than one field in the filters array as long as you are filtering single data type. Using more than one field allows you to refine the search results to meet all of the specified search conditions.

You can expand the following example of a POST request to initiate an export request with more than one field. In the following example, the request filters CALCULATED_PRICE by both priceType and priceListIds:

Click here to expand and see the request payload.

curl --request POST \
  --url https://live.copilot.fabric.inc/api-offers/offers-exports \
  --header 'Authorization: Bearer exampleToken123' \
  --header 'Content-Type: application/json' \
  --header 'x-fabric-tenant-id: exampleTenantID456' \
  --data '{
  "type": "CALCULATED_PRICE",
  "filters": [
    {
      "field": "priceType",
      "value": "BASE",
      "operator": "EQUAL"
    },
    {
      "field": "priceListIds",
      "value": [
        1000003,
        1000004
      ],
      "operator": "IN"
    }
  ]
}'

A successful request returns the following response:

Click here to expand and see the response.

{
  "exportId": "4a73a9a9-b8c3-4dc1-a467-c528a1b2dfe7",
  "startedAt": "2023-12-01T10:33:33.638Z",
  "endedAt": "null",
  "totalDataExported": 0,
  "status": "IN_PROGRESS",
  "errors": [],
  "type": "CALCULATED_PRICE",
  "filters": [
    {
      "field": "priceType",
      "value": "BASE",
      "operator": "EQUAL"
    },
    {
      "field": "priceListIds",
      "value": [
        1000003,
        1000004
      ],
      "operator": "IN"
    }
  ]
}

Retrieving all export requests

If you have initiated multiple export requests, you can retrieve details of all export requests using the Get all export requests endpoint. A successful request returns an array containing details of all export request details, including the respective fieldId values. You can expand the following example to see the GET response:

Click here to expand and see the response.

{
  "query": {
    "size": 10,
    "offset": 10,
    "count": 50
  },
  "data": [
    {
      "exportId": "ab50fe48-5da0-4e77-92d1-bb629eedf19e",
      "startedAt": "2023-05-17T21:24:52.398Z",
      "endedAt": "null",
      "status": "IN_PROGRESS",
      "type": "REDEMPTION",
      "totalDataExported": 0,
      "fileId": "redemption/tenantId/1687294954996-redemption-export.csv"
    },
    {
      "exportId": "4a73a9a9-b8c3-4dc1-a467-c528a1b2dfe7",
      "startedAt": "2023-12-01T10:33:33.638Z",
      "endedAt": "null",
      "status": "IN_PROGRESS",
      "type": "CALCULATED_PRICE",
      "totalDataExported": 0,
      "fileId": "redemption/tenantId/5900139542278-calculated-price-export.csv"
    }
  ]
}

Troubleshooting

EXPORT_CALCULATED_PRICE_ERROR

If you get the EXPORT_CALCULATED_PRICE_ERROR error after initiating an export request, resubmit the request. If the problem persists, contact fabric support.

Exported file is incomplete

If your exported CSV is incomplete, use the get export request endpoint and ensure that the status is marked as COMPLETE. If the status remains IN_PROGRESS after the 10-hours, try the request again or contact fabric support.

CSV file download link not working

The download link is valid for only 5 minutes. If the link has expired, generate the link again using the download exported CSV file endpoint. If the problem persists, contact fabric support.

Related Topics

• Initiate export request
• Get export request by ID
• Get all export requests
• Download exported CSV file