AWS Marketplace guide

01How it works

A marketplace product belongs to one tenant and lists the workflows its buyers may run. Each AWS buyer becomes a subscription under that product, holding its own mk_ API keys. AWS bills the buyer; Datacove reports each buyer's usage to AWS every hour.

02AWS seller setup

Done once per seller AWS account, in us-east-1, where the AWS Marketplace APIs run. Every value below is saved on the tenant (section 03), never in server configuration, because each tenant can sell from its own account.

Event queue

1. Create a standard SQS queue (not FIFO), plus a second one as its dead-letter queue with maximum receives 5. Visibility timeout 60 seconds, retention 4 days or more. The backend reads it every minute and deletes each message once stored.
2. Give the queue an access policy that lets SNS and EventBridge deliver to it:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowMarketplaceSns",
      "Effect": "Allow",
      "Principal": { "Service": "sns.amazonaws.com" },
      "Action": "sqs:SendMessage",
      "Resource": "arn:aws:sqs:us-east-1:<seller-account-id>:<queue-name>",
      "Condition": { "ArnEquals": { "aws:SourceArn": [
        "arn:aws:sns:us-east-1:<aws-owned-account>:aws-mp-subscription-notification-<product-code>"
      ] } }
    },
    {
      "Sid": "AllowMarketplaceEventBridge",
      "Effect": "Allow",
      "Principal": { "Service": "events.amazonaws.com" },
      "Action": "sqs:SendMessage",
      "Resource": "arn:aws:sqs:us-east-1:<seller-account-id>:<queue-name>",
      "Condition": { "ArnEquals": {
        "aws:SourceArn": "arn:aws:events:us-east-1:<seller-account-id>:rule/<rule-name>"
      } }
    }
  ]
}

Credentials

Create one IAM policy and attach it either to an IAM user whose access keys are saved on the tenant, or to a role the backend assumes with an external ID.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "MarketplaceApis",
      "Effect": "Allow",
      "Action": [
        "aws-marketplace:ResolveCustomer",
        "aws-marketplace:BatchMeterUsage",
        "aws-marketplace:GetEntitlements",
        "aws-marketplace:DescribeAgreement",
        "aws-marketplace:GetAgreementTerms",
        "aws-marketplace:DescribeEntity",
        "aws-marketplace:PutDeploymentParameter"
      ],
      "Resource": "*"
    },
    {
      "Sid": "EventQueue",
      "Effect": "Allow",
      "Action": ["sqs:ReceiveMessage", "sqs:DeleteMessage", "sqs:GetQueueAttributes"],
      "Resource": "arn:aws:sqs:us-east-1:<seller-account-id>:<queue-name>"
    },
    {
      "Sid": "BillingDataFeed",
      "Effect": "Allow",
      "Action": ["s3:ListBucket", "s3:GetObject"],
      "Resource": ["arn:aws:s3:::<feed-bucket>", "arn:aws:s3:::<feed-bucket>/*"]
    }
  ]
}

Listing settings

The listing and the Datacove product must agree on these, or usage is rejected by AWS or priced wrongly in reports.

Billing data feed (optional)

To replace revenue estimates with what AWS actually invoiced, subscribe the seller account to AWS Marketplace seller data feeds (AWS Marketplace Management Portal → Set up customer data storage), delivered to an encrypted S3 bucket in the seller account. Save the bucket on the tenant as dataFeedBucket, with dataFeedPrefix if the feeds live under a key prefix. The billing event feed is then imported every day (section 06).

03Platform setup

Both steps are SUPER_ADMIN calls, usually made from the admin panel.

Tenant settings

Products

{
  "tenantId": "<tenant id>",
  "name": "URL Threat Check API",
  "externalProductId": "prod-xxxxxxxxxxxx",
  "productCode": "<product code>",
  "fulfillmentMode": "redirect",
  "notificationChannel": "eventbridge",
  "pricing": {
    "type": "pay_as_you_go",
    "payAsYouGo": { "dimensionKey": "api_call", "pricePerCallUsd": 0.05 }
  },
  "allowedWorkflows": ["wf-sec-001"],
  "keyLifetimeDays": 365
}

"pricing": {
  "type": "plans",
  "plans": [{
    "key": "starter",
    "name": "Starter",
    "dimensionKey": "starter_tier",
    "priceUsd": 499,
    "durationMonths": 12,
    "callLimit": 10000,
    "resetEvery": "monthly"
  }],
  "onLimit": {
    "action": "overage",
    "dimensionKey": "overage_call",
    "pricePerCallUsd": 0.08
  }
}

04Tenant signup page

The tenant website owns the page and its design. AWS posts the buyer to the fulfillment URL; the backend identifies them with AWS and redirects the browser to signupPageUrl with either ?session=<token> or ?error=<code>. The page then talks to the API with the tenant website's own dk_ key.

{
  "productName": "URL Threat Check API",
  "pricing": { "type": "pay_as_you_go", "payAsYouGo": { "dimensionKey": "api_call", "pricePerCallUsd": 0.05 } },
  "status": "pending_activation",
  "isRegistered": true,
  "isFreeTrial": false,
  "contact": { "name": "Priya Sharma", "email": "priya@example.com", "company": "Example Corp" },
  "hasKey": false,
  "canRevealKey": false,
  "supportEmail": "support@example.com",
  "expiresAt": "2026-10-15T10:30:00.000Z"
}

Publishing API docs

The tenant website can also host the buyers' API reference, generated live from the product, so it never goes stale. Fetch the document from the website's server with the same dk_ key and render it with any OpenAPI viewer (Redoc, Scalar, Swagger UI). Buyer keys and other callers are refused.

Workflows that need a file upload are left out, as they are from the agent spec. Point the signup page's "API docs" link at the page that renders this document.

05Calling the API as a buyer

Buyers send their key as x-api-key: mk_… on every call, from their own servers or an agent gateway. There is no token exchange and no browser origin check. The key works only while the subscription is active.

Running workflows

curl -X POST "$BASE_URL/workflows/v1/execute" \
  -H "x-api-key: mk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "id": "wf-sec-001", "input": { "url": "https://example.com/login" } }'

# Queue it, then poll the report every 5 s
curl -X POST "$BASE_URL/workflows/v1/execute?callAsync=true" …
# → { "success": true, "eventId": "…" }
curl "$BASE_URL/workflows/reports/v1/<eventId>" -H "x-api-key: mk_live_…"

Agent tools

Sellers get the same document for the listing from GET /marketplace/products/v1/:id/agent-spec (SUPER_ADMIN).

Rotating a key

06Metering and revenue

Dashboards show marketplace revenue in a separate USD bucket, and workflow stats show marketplace runs and revenue in their own block; neither is ever mixed into INR or CAD earnings. When an invoice replaces estimates, the dashboard is corrected by the difference, so nothing is counted twice.

07Operations

SUPER_ADMIN endpoints for support and finance. Every change is written to the audit log.

08Errors

Errors use the platform envelope. Branch on the status, then on error.code.

{
  "statusCode": 429,
  "timestamp": "2026-10-15T09:30:00.000Z",
  "path": "/api/workflows/v1/execute",
  "error": {
    "code": "PLAN_LIMIT_REACHED",
    "message": "Your plan's call allowance is used up. It resets on 2026-11-01T00:00:00.000Z.",
    "resetsAt": "2026-11-01T00:00:00.000Z"
  }
}