Create an Action Plan to Address an Action Item

Learn how to take an Action Item from discovery through execution: list actionable items, preview the plan Amazon would run, get the selling partner's explicit confirmation, create the plan, and poll it to a terminal state. This tutorial uses the cross-store expansion within Europe (the EXPAND_CROSS_STORE resolution type), to illustrate the flow. A full expansion takes from roughly four hours up to three days; listings appear in the target store early in that window and can show missing-offer or missing-information states while setup continues asynchronously. This is normal, and should not be reported as a broken expansion.

🚧

Caution

Creating an Action Plan performs real work: it changes the authorized seller's account and cannot be undone through these APIs. Develop against the sandbox and create a plan only for a seller who has confirmed the action.

Prerequisites

To complete this tutorial, you need:

• Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.
• The Selling Partner Insights role assigned to your developer profile and selected in the App registration page for your application.
• The regional endpoint for the seller. For sellers in Europe, use https://sellingpartnerapi-eu.amazon.com. The host declared in the API model is North America; do not use it for European sellers.

Step 1. List actionable items

Call the listActionItems operation with a statuses filter and includedData=resolutions:

GET /actionItems/2026-06-01/items?statuses=PENDING_SELLING_PARTNER&includedData=resolutions&locale=en-US
Host: sellingpartnerapi-eu.amazon.com

Always pass a statuses filter; an unfiltered list also returns dismissed and resolved items. Always request includedData=resolutions, since without it the response omits the resolutions and the plan template identifier needed for every later call. The response contains the items and, inside each resolution, the plan template reference:

{
  "actionItems": [
    {
      "actionItemId": "29rpnt85vjn3qkvW7SwsLUsn9...",
      "type": {
        "classifications": ["RECOMMENDATION"],
        "definition": {
          "typeDefinitionId": "AFN_CROSS_STORE_EXPANSION",
          "displayName": { "text": "Cross-store expansion (FBA)", "locale": "en-US" }
        }
      },
      "description": {
        "text": "Grow your business by listing your Amazon.de catalog in the Amazon.fr store using Fulfillment by Amazon. Amazon configures pricing and copies your offers.",
        "locale": "en-US"
      },
      "status": ["PENDING_SELLING_PARTNER", "AUTOMATABLE", "DISMISSABLE"],
      "resolutions": [
        {
          "type": "EXPAND_CROSS_STORE",
          "definition": {
            "resolutionDefinitionId": "AFN_CROSS_STORE_EXPANSION",
            "displayName": { "text": "Run the guided cross-store expansion plan", "locale": "en-US" }
          },
          "actionPlans": [
            { "actionPlanTemplateId": "AFN_CROSS_STORE_EXPANSION" }
          ]
        }
      ],
      "lastUpdatedDate": "2026-09-02T08:47:24.805Z",
      "dueDate": "2026-09-09T08:47:24.805Z"
    }
  ]
}

📘

Note

The example truncates actionItemId for readability; production values exceed 120 characters. status is an array, not a single value: an item you can act on carries both PENDING_SELLING_PARTNER and AUTOMATABLE. Do not assume every item is automatable.

Select an item only when one of its resolutions has a non-empty actionPlans array. A resolution that carries only a url is a manual pathway; link the seller to it rather than creating a plan.

Other status values you may see on an Action Item:

• DISMISSED: The seller dismissed it.
• ACTIONED: An action has already been taken on it. For example, an Action Plan was created for it.
• OVERDUE: It passed its due date.
• RESOLVED: It is resolved.

To list items in one of these states instead of the actionable queue, filter statuses accordingly, for example statuses=DISMISSED or statuses=RESOLVED. To check for new or changed items since your last sync, add updatedAfter=<ISO-8601> instead of re-fetching everything.

Step 2. Capture the identifiers for the chosen resolution

Build every later call from values read out of the step 1 response rather than constructed by your application:

📘

Note

Read the resolutionDefinitionId and the planTemplateId from the same resolution entry; do not combine values from different resolutions. Do not derive the template from typeDefinitionId or from resolutionDefinitionId; the values look alike for cross-store expansion, but the contract does not guarantee they stay equal. If the resolution already carries an actionPlanId, a plan already exists for it: open that plan instead of creating another. Request includedData=references on listActionItems to see the item-level references.actionPlans array, which lists every plan instance created for the item.

Step 3. Preview the plan

Call the createActionPlan operation with mode=PREVIEW to get the full plan, including its name, steps, and inputs, without persisting anything:

POST /actionPlans/2026-06-01/plans?mode=PREVIEW&locale=en-US
Content-Type: application/json

{
  "planTemplateId": "AFN_CROSS_STORE_EXPANSION",
  "actionItem": {
    "actionItemId": "29rpnt85vjn3qkvW7SwsLUsn9...",
    "resolution": {
      "definition": {
        "resolutionDefinitionId": "AFN_CROSS_STORE_EXPANSION"
      }
    }
  }
}

Amazon derives the plan inputs from the Action Item context; for cross-store expansion, these include the source and target stores. Send the item identifier together with the resolution. Do not send the inputs field; requests that include it return HTTP 400, as does a request that omits resolutionDefinitionId. A request payload that is too large returns HTTP 413, and an unsupported media type returns HTTP 415; both indicate a malformed request rather than a transient error, so fix the request instead of retrying.

📘

Note

The response returns a preview of the plan inside a plan envelope: a localized plan name, the inputs, and the ordered steps with their descriptions. In the preview, the plan's status is DRAFT and each step is NOT_STARTED. Nothing is persisted, so do not store or reuse any actionPlanId from a preview response. Render the returned steps, names, and descriptions rather than hard-coding them, since templates evolve and a new template then does not require a client release.

Step 4. Obtain the seller's explicit confirmation

The API has no separate accept operation, so your application owns the consent screen between preview and create. At minimum:

• Show the item description and the resolved plan steps from the preview.
• State that starting the plan creates and executes it immediately.
• State that it cannot be undone through these APIs.
• Require an explicit confirm action.

Step 5. Create the plan

Call createActionPlan again with the same request body, omitting mode:

POST /actionPlans/2026-06-01/plans?locale=en-US
Content-Type: application/json

{
  "planTemplateId": "AFN_CROSS_STORE_EXPANSION",
  "actionItem": {
    "actionItemId": "29rpnt85vjn3qkvW7SwsLUsn9...",
    "resolution": {
      "definition": {
        "resolutionDefinitionId": "AFN_CROSS_STORE_EXPANSION"
      }
    }
  }
}

A successful call returns HTTP 200 with the created plan in the plan envelope. Capture plan.actionPlanId immediately:

{
  "plan": {
    "actionPlanId": "e5f6a7b8-89ab-cdef-0123-456789abcdef",
    "status": ["PROCESSING"],
    "createdDate": "2026-09-08T10:00:00Z"
  }
}

1. Call listActionPlans with actionItemIds=<actionItemId>.
2. If a plan exists for your actionItemId, use it and do not create again.
3. If the result is ambiguous, stop and contact your Amazon point of contact rather than retrying.

Running the same check immediately before every create also narrows the duplicate window when a seller confirms twice. If the create request itself returns HTTP 409, the resolution is already in a conflicting state; re-read the Action Item and Action Plan rather than repeating the request unchanged. For HTTP 429, retry reads with exponential backoff, but never auto-retry createActionPlan itself. The response header x-amzn-RateLimit-Limit reports your rate limit, in requests per second, for the operation you called.

Step 6. Poll the plan to a terminal state

Call getActionPlan with includedData=steps to include detailed input and output values for each step; step metadata itself is always included:

GET /actionPlans/2026-06-01/plans/{actionPlanId}?includedData=steps&locale=en-US

To check progress for one item instead, call listActionPlans with actionItemIds=..., or statuses=PROCESSING to find everything still executing and statuses=DONE,PARTIAL to find everything that finished. Add createdAfter=<ISO-8601> instead of re-fetching everything when checking for plans created since your last sync; listActionPlans has no updatedAfter filter. Filters that accept multiple values, such as statuses, use OR semantics: a result matches when it carries any supplied value.

status on both plans and steps is an array; treat it as a set rather than a single value:

• A plan is terminal when its status contains DONE, PARTIAL, or CANCELLED. Test for all three; a plan with failed steps can report PARTIAL without DONE. CANCELLED exists as an enum value, but there is no cancel operation.
• PARTIAL means the plan finished with some work not performed or failed; inspect every step. There is no plan-level FAILED status, so never wait for one.
• PROCESSING means Amazon is still executing the plan. PENDING_SELLING_PARTNER means the plan itself is waiting on a selling partner action, distinct from the same status on the originating Action Item.
• For a step's outcome, check in order: FAILED, SUCCEEDED, SKIPPED, then the generic COMPLETED. A step reports NOT_STARTED before execution reaches it, and PENDING_DEPENDENCY while waiting on the steps named in its dependencies.
• completedDate is set when the plan reaches a terminal state; use it to cross-check the status.
• Report failures at step level. The Action Item states the opportunity; execution state belongs to the plan.

Step 7. Close the loop

When the plan reaches a terminal state, refresh the originating Action Item by calling getActionItem. Keep the item out of your actionable queue once it is ACTIONED or RESOLVED.

📘

Note

If getActionItem or getActionPlan returns HTTP 404, the identifier is unknown; re-list the resource, since the item or plan may have expired. If getActionPlan returns HTTP 403, check that your application is authorized for the Selling Partner Insights role and that the token matches the seller.