Skip to content

Partner Orders

Decline a partner order and refund it

Turn down a paid order before sending a proof, with a note to the director. The director is refunded in full through Stripe, the partner's transfer and Endurance HQ's fee included, and the order closes as refunded. Cannot be undone. Refused (409) once a proof has gone out. Returns the order as partnerOrders.get reads it. Requires partner-orders:write.

Method

POST

Path

/v1/partner-orders/{orderId}/decline

Required scope

partner-orders:write

Request

curl -X POST "https://api.endurancehq.app/v1/partner-orders/{orderId}/decline" \
  -H "Authorization: Bearer $EHQ_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Path parameters

orderIdstring, required

JSON body schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "note": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000,
      "description": "Why, for the director."
    }
  },
  "required": [
    "note"
  ],
  "additionalProperties": false
}

Response

Success status: 200

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "service": {
          "type": "string",
          "enum": [
            "course_maps",
            "goods"
          ],
          "description": "course_maps (a course or venue map order) or goods (a medals and printing order)."
        },
        "order": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "status": {
              "type": "string",
              "enum": [
                "paid",
                "in_progress",
                "proof_ready",
                "changes_requested",
                "in_production",
                "shipped",
                "delivered",
                "refunded"
              ],
              "description": "paid (waiting for the partner to start), in_progress, proof_ready (waiting on the director), changes_requested, in_production (goods: approved, being made), shipped (goods), delivered (finished) or refunded (declined and refunded in full)."
            },
            "offeringLabel": {
              "type": "string"
            },
            "notes": {
              "type": [
                "string",
                "null"
              ]
            },
            "currentRound": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            "includedRevisions": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991
            },
            "partnerCents": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991,
              "description": "What the partner is paid for this order, in the smallest unit of currency."
            },
            "totalCents": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991,
              "description": "What the director paid."
            },
            "feeCents": {
              "type": "integer",
              "minimum": -9007199254740991,
              "maximum": 9007199254740991,
              "description": "Endurance HQ's part of the total."
            },
            "currency": {
              "type": "string"
            },
            "broughtBy": {
              "type": "string",
              "enum": [
                "platform",
                "partner"
              ],
              "description": "partner when the order came from the partner's own client."
            },
            "director": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "email": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "organizationName": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "name",
                    "email",
                    "organizationName"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "null"
                }
              ],
              "description": "Who placed an order the partner brought (its own client); null on every other order."
            },
            "paidAt": {
              "type": [
                "string",
                "null"
              ]
            },
            "activity": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "at": {
                    "type": "string"
                  },
                  "by": {
                    "type": "string",
                    "enum": [
                      "organizer",
                      "partner",
                      "system"
                    ]
                  },
                  "kind": {
                    "type": "string",
                    "description": "ordered, paid, started, proof, changes, approved, production, shipped, received, declined, refunded or note."
                  },
                  "note": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "at",
                  "by",
                  "kind",
                  "note"
                ],
                "additionalProperties": {}
              }
            },
            "files": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "round": {
                    "type": "integer",
                    "minimum": -9007199254740991,
                    "maximum": 9007199254740991,
                    "description": "0 for the director's artwork (goods), then 1, 2 and so on for each proof round."
                  },
                  "name": {
                    "type": "string"
                  },
                  "contentType": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "sizeBytes": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "minimum": -9007199254740991,
                        "maximum": 9007199254740991
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "createdAt": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "round",
                  "name",
                  "contentType",
                  "sizeBytes",
                  "createdAt"
                ],
                "additionalProperties": {}
              },
              "description": "Every round of files, newest round first. Download each through links.files."
            },
            "brief": {
              "description": "Map orders: the event and each course (distance, elevation, time limit, route file, start, finish, aid stations), and the venue layers.",
              "type": "object",
              "propertyNames": {
                "type": "string"
              },
              "additionalProperties": {}
            },
            "event": {
              "description": "Goods orders: the event the goods are for.",
              "type": "object",
              "propertyNames": {
                "type": "string"
              },
              "additionalProperties": {}
            }
          },
          "required": [
            "id",
            "status",
            "offeringLabel",
            "notes",
            "currentRound",
            "includedRevisions",
            "partnerCents",
            "totalCents",
            "feeCents",
            "currency",
            "broughtBy",
            "director",
            "paidAt",
            "activity",
            "files"
          ],
          "additionalProperties": {}
        },
        "links": {
          "type": "object",
          "properties": {
            "files": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "downloadUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "Needs the same key, with partner-orders:read."
                  }
                },
                "required": [
                  "id",
                  "downloadUrl"
                ],
                "additionalProperties": false
              }
            },
            "maps": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "targetKey": {
                    "type": "string",
                    "description": "The distance's id, or site for the venue map."
                  },
                  "name": {
                    "type": "string"
                  },
                  "gpxUrl": {
                    "description": "The route file the director keeps current; null for the venue map or a course without one.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "geoJsonUrl": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "uri"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "The map's live geometry, while the order is open (paid through changes requested); null after."
                  },
                  "kmlUrl": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "uri"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "targetKey",
                  "name",
                  "gpxUrl",
                  "geoJsonUrl",
                  "kmlUrl"
                ],
                "additionalProperties": false
              },
              "description": "Map orders only: each map the order covers. Empty for goods orders."
            }
          },
          "required": [
            "files",
            "maps"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "service",
        "order",
        "links"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "data"
  ],
  "additionalProperties": false
}

Other surfaces

MCP tool: ehq_partner_orders_decline