create-billing-transfer-reseller-handshakes

dci create-billing-transfer-reseller-handshakes [flags]

Maps reseller to distributor; also sends the handshake if required, as part of AWS billing transfer onboarding. Distributor-only; callers without the ChannelOps distributor tier entitlement receive 403.

Each item in the batch is processed independently; per-item outcomes are returned in results[] with HTTP 200 even when some items fail. Malformed items (missing fields, duplicate resellerPmaAccountId within the batch) are rejected up front with 422 and reported in invalidItems, and none of the batch is processed in that case.

Request

Content-Type: application/json

Schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "dpmaId",
    "items"
  ],
  "properties": {
    "dpmaId": {
      "type": "string",
      "description": "The distributor's program management account (DPMA) ID issuing the handshakes."
    },
    "sendHandshakes": {
      "type": "boolean",
      "description": "If `true`, issues a new AWS Organizations handshake for each item without an existing one. If omitted or `false`, maps the batch in place without issuing any AWS Organizations handshakes.",
      "default": false
    },
    "items": {
      "type": "array",
      "minItems": 1,
      "maxItems": 100,
      "description": "Batch items. Duplicate `resellerPmaAccountId` values within the batch are rejected.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "resellerCustomerId",
          "resellerPmaAccountId"
        ],
        "properties": {
          "resellerCustomerId": {
            "type": "string",
            "description": "DoiT customer ID of the reseller's end customer to issue a handshake for."
          },
          "resellerPmaAccountId": {
            "type": "string",
            "description": "12-digit AWS account ID of the reseller's program management account (PMA).",
            "example": "123456789012"
          }
        }
      }
    }
  }
}

Flags

--dry-run: (boolean default:false)

Responses

200 (application/json)

OK - Batch processed; see results and summary for per-item outcomes.

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "dpmaId",
    "results",
    "summary"
  ],
  "properties": {
    "dpmaId": {
      "type": "string"
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "resellerCustomerId",
          "resellerPmaAccountId",
          "status"
        ],
        "properties": {
          "resellerCustomerId": {
            "type": "string"
          },
          "resellerPmaAccountId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "description": "Outcome of processing this batch item.",
            "enum": [
              "handshake_issued",
              "no_op",
              "mapped",
              "remapped",
              "failed"
            ]
          },
          "handshakeId": {
            "type": "string",
            "description": "AWS Organizations handshake ID. Absent when no handshake was issued (e.g. `no_op`, `failed`, or dry run)."
          },
          "handshakeState": {
            "type": "string",
            "description": "AWS Organizations Handshake `State` value, lowercased.",
            "enum": [
              "requested",
              "open",
              "canceled",
              "accepted",
              "declined",
              "expired"
            ]
          },
          "error": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code for this item."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the failure."
              }
            }
          }
        }
      }
    },
    "summary": {
      "type": "object",
      "description": "Per-outcome counts across the batch. Field names are snake_case, matching the actual wire format returned by this endpoint — an intentional inconsistency with the rest of the payload, which is camelCase.",
      "additionalProperties": false,
      "required": [
        "handshake_issued",
        "no_op",
        "mapped",
        "remapped",
        "failed"
      ],
      "properties": {
        "handshake_issued": {
          "type": "integer"
        },
        "no_op": {
          "type": "integer"
        },
        "mapped": {
          "type": "integer"
        },
        "remapped": {
          "type": "integer"
        },
        "failed": {
          "type": "integer"
        }
      }
    }
  }
}

400 (application/json)

Bad Request - The server cannot process the request, often due to a malformed request.

{
  "type": "object",
  "description": "Standard error response structure.",
  "properties": {
    "error": {
      "type": "string",
      "description": "Detailed error message."
    }
  }
}

401 (application/json)

Unauthorized - Invalid API key.

{
  "type": "object",
  "description": "Standard error response structure.",
  "properties": {
    "error": {
      "type": "string",
      "description": "Detailed error message."
    }
  }
}

403 (application/json)

Forbidden - The caller is not entitled to the ChannelOps distributor tier, or does not own the referenced dpmaId.

{
  "type": "object",
  "description": "RFC 7807 problem-detail body returned by Billing Transfer endpoints for 4xx/5xx errors.",
  "additionalProperties": false,
  "required": [
    "type",
    "title",
    "status",
    "code"
  ],
  "properties": {
    "type": {
      "type": "string",
      "format": "uri",
      "description": "A URI identifying the problem type."
    },
    "title": {
      "type": "string",
      "description": "Short, human-readable summary of the problem type."
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status code repeated in the body."
    },
    "detail": {
      "type": "string",
      "description": "Human-readable explanation specific to this occurrence of the problem."
    },
    "code": {
      "type": "string",
      "description": "Stable machine-readable error code.",
      "example": "billing-transfer.batch_validation_failed"
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether retrying the same request may succeed without changes."
    },
    "invalidItems": {
      "type": "array",
      "description": "Present on batch-validation failures; the batch items that failed validation.",
      "items": {
        "type": "object",
        "description": "A single batch item that failed validation before processing began.",
        "additionalProperties": false,
        "required": [
          "index",
          "code"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "description": "Zero-based position of the invalid item within the submitted batch."
          },
          "resellerCustomerId": {
            "type": "string",
            "description": "Present when the invalid item is a reseller-handshake batch item."
          },
          "code": {
            "type": "string",
            "description": "Stable machine-readable error code (e.g. `duplicate_pma`, `duplicate_ec_account`).",
            "example": "duplicate_pma"
          },
          "reason": {
            "type": "string",
            "description": "Human-readable explanation of why the item is invalid."
          }
        }
      }
    }
  }
}

422 (application/json)

Unprocessable Entity - One or more items in the batch failed validation before any processing began (missing required fields, or duplicate account/customer IDs within the batch), or a batch-level field such as dpmaId is missing or invalid. None of the batch was processed; resubmit with corrected items. Invalid items are listed in invalidItems.

{
  "type": "object",
  "description": "RFC 7807 problem-detail body returned by Billing Transfer endpoints for 4xx/5xx errors.",
  "additionalProperties": false,
  "required": [
    "type",
    "title",
    "status",
    "code"
  ],
  "properties": {
    "type": {
      "type": "string",
      "format": "uri",
      "description": "A URI identifying the problem type."
    },
    "title": {
      "type": "string",
      "description": "Short, human-readable summary of the problem type."
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status code repeated in the body."
    },
    "detail": {
      "type": "string",
      "description": "Human-readable explanation specific to this occurrence of the problem."
    },
    "code": {
      "type": "string",
      "description": "Stable machine-readable error code.",
      "example": "billing-transfer.batch_validation_failed"
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether retrying the same request may succeed without changes."
    },
    "invalidItems": {
      "type": "array",
      "description": "Present on batch-validation failures; the batch items that failed validation.",
      "items": {
        "type": "object",
        "description": "A single batch item that failed validation before processing began.",
        "additionalProperties": false,
        "required": [
          "index",
          "code"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "description": "Zero-based position of the invalid item within the submitted batch."
          },
          "resellerCustomerId": {
            "type": "string",
            "description": "Present when the invalid item is a reseller-handshake batch item."
          },
          "code": {
            "type": "string",
            "description": "Stable machine-readable error code (e.g. `duplicate_pma`, `duplicate_ec_account`).",
            "example": "duplicate_pma"
          },
          "reason": {
            "type": "string",
            "description": "Human-readable explanation of why the item is invalid."
          }
        }
      }
    }
  }
}

500 (application/json)

Internal Server Error - Something went wrong with the DoiT API server.

{
  "type": "object",
  "description": "Standard error response structure.",
  "properties": {
    "error": {
      "type": "string",
      "description": "Detailed error message."
    }
  }
}

502 (application/json)

Bad Gateway - AWS Organizations was unreachable; retry later.

{
  "type": "object",
  "description": "RFC 7807 problem-detail body returned by Billing Transfer endpoints for 4xx/5xx errors.",
  "additionalProperties": false,
  "required": [
    "type",
    "title",
    "status",
    "code"
  ],
  "properties": {
    "type": {
      "type": "string",
      "format": "uri",
      "description": "A URI identifying the problem type."
    },
    "title": {
      "type": "string",
      "description": "Short, human-readable summary of the problem type."
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status code repeated in the body."
    },
    "detail": {
      "type": "string",
      "description": "Human-readable explanation specific to this occurrence of the problem."
    },
    "code": {
      "type": "string",
      "description": "Stable machine-readable error code.",
      "example": "billing-transfer.batch_validation_failed"
    },
    "retryable": {
      "type": "boolean",
      "description": "Whether retrying the same request may succeed without changes."
    },
    "invalidItems": {
      "type": "array",
      "description": "Present on batch-validation failures; the batch items that failed validation.",
      "items": {
        "type": "object",
        "description": "A single batch item that failed validation before processing began.",
        "additionalProperties": false,
        "required": [
          "index",
          "code"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "description": "Zero-based position of the invalid item within the submitted batch."
          },
          "resellerCustomerId": {
            "type": "string",
            "description": "Present when the invalid item is a reseller-handshake batch item."
          },
          "code": {
            "type": "string",
            "description": "Stable machine-readable error code (e.g. `duplicate_pma`, `duplicate_ec_account`).",
            "example": "duplicate_pma"
          },
          "reason": {
            "type": "string",
            "description": "Human-readable explanation of why the item is invalid."
          }
        }
      }
    }
  }
}

Aliases: createbillingtransferresellerhandshakes