One platform, every department, powered by AI.

My accountMy account
carsoft.ai

Partner API reference.

0.2.0-draft · Explore endpoints, authentication and schemas.

Download contractAll versions
Readiness and contract scope

Local implementation under verification; not deployed

Local implementation under verification. Production not activated/deployed. This draft covers implemented resource, intake, token, payment-intent and event-subscription routes. Resource/OAuth behavior has local HTTP tests; financial adapters have not completed processor sandbox acceptance. Invoice, developer lifecycle, export and billing interfaces remain incomplete.

This is an archived contract snapshot. Refer to the current version for active service details.

Authentication contracts

Use the authentication declared for each operation. Developer identity and partner app OAuth grant different access.

{
  "partnerToken": {
    "type": "oauth2",
    "flows": {
      "authorizationCode": {
        "authorizationUrl": "https://app.carsoft.ai/partners/authorize",
        "tokenUrl": "https://app.carsoft.ai/api/partners/oauth/token",
        "scopes": {
          "inventory:read": "inventory:read",
          "inventory:create": "inventory:create",
          "inventory:update": "inventory:update",
          "leads:read": "leads:read",
          "leads:create": "leads:create",
          "leads:update": "leads:update",
          "clients:read": "clients:read",
          "clients:create": "clients:create",
          "clients:update": "clients:update",
          "service:read": "service:read",
          "service:create": "service:create",
          "service:update": "service:update",
          "parts:read": "parts:read",
          "parts:create": "parts:create",
          "parts:update": "parts:update",
          "appointments:read": "appointments:read",
          "appointments:create": "appointments:create",
          "appointments:update": "appointments:update",
          "invoices:read": "invoices:read",
          "invoices:create": "invoices:create",
          "invoices:draft-update": "invoices:draft-update",
          "payments:links": "payments:links",
          "payments:read": "payments:read",
          "payments:charge": "payments:charge",
          "payments:refund": "payments:refund",
          "events:subscribe": "events:subscribe",
          "exports:create": "exports:create"
        }
      }
    }
  }
}

Endpoints 19

GETPOST/api/partners/v1/inventory
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "operationId": "listinventory",
  "tags": [
    "Vehicle inventory"
  ],
  "security": [
    {
      "partnerToken": [
        "inventory:read"
      ]
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "maxLength": 128
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Records ordered by ID",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/inventoryRecord"
                }
              },
              "pagination": {
                "type": "object",
                "properties": {
                  "next": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "limit": {
                    "type": "integer"
                  }
                },
                "required": []
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
POST · Operation details

Declared responses: 201, default

Full operation contract
{
  "operationId": "createinventory",
  "tags": [
    "Vehicle inventory"
  ],
  "security": [
    {
      "partnerToken": [
        "inventory:create"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/inventoryCreate"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/inventoryRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
GETPATCH/api/partners/v1/inventory/{id}
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "operationId": "getinventory",
  "tags": [
    "Vehicle inventory"
  ],
  "security": [
    {
      "partnerToken": [
        "inventory:read"
      ]
    }
  ],
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/inventoryRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
PATCH · Operation details

Declared responses: 200, default

Full operation contract
{
  "operationId": "updateinventory",
  "tags": [
    "Vehicle inventory"
  ],
  "security": [
    {
      "partnerToken": [
        "inventory:update"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    },
    {
      "in": "header",
      "name": "If-Match",
      "required": true,
      "schema": {
        "type": "string",
        "pattern": "^\"[1-9][0-9]*\"$"
      },
      "description": "ETag from last GET. Stale updates return 409."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/inventoryUpdate"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/inventoryRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
GETPOST/api/partners/v1/leads
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "operationId": "listleads",
  "tags": [
    "Leads"
  ],
  "security": [
    {
      "partnerToken": [
        "leads:read"
      ]
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "maxLength": 128
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Records ordered by ID",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/leadsRecord"
                }
              },
              "pagination": {
                "type": "object",
                "properties": {
                  "next": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "limit": {
                    "type": "integer"
                  }
                },
                "required": []
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
POST · Operation details

Declared responses: 201, default

Full operation contract
{
  "operationId": "createleads",
  "tags": [
    "Leads"
  ],
  "security": [
    {
      "partnerToken": [
        "leads:create"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/leadsCreate"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/leadsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
GETPATCH/api/partners/v1/leads/{id}
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "operationId": "getleads",
  "tags": [
    "Leads"
  ],
  "security": [
    {
      "partnerToken": [
        "leads:read"
      ]
    }
  ],
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/leadsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
PATCH · Operation details

Declared responses: 200, default

Full operation contract
{
  "operationId": "updateleads",
  "tags": [
    "Leads"
  ],
  "security": [
    {
      "partnerToken": [
        "leads:update"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    },
    {
      "in": "header",
      "name": "If-Match",
      "required": true,
      "schema": {
        "type": "string",
        "pattern": "^\"[1-9][0-9]*\"$"
      },
      "description": "ETag from last GET. Stale updates return 409."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/leadsUpdate"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/leadsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
GETPOST/api/partners/v1/clients
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "operationId": "listclients",
  "tags": [
    "Customers"
  ],
  "security": [
    {
      "partnerToken": [
        "clients:read"
      ]
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "maxLength": 128
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Records ordered by ID",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/clientsRecord"
                }
              },
              "pagination": {
                "type": "object",
                "properties": {
                  "next": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "limit": {
                    "type": "integer"
                  }
                },
                "required": []
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
POST · Operation details

Declared responses: 201, default

Full operation contract
{
  "operationId": "createclients",
  "tags": [
    "Customers"
  ],
  "security": [
    {
      "partnerToken": [
        "clients:create"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/clientsCreate"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/clientsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
GETPATCH/api/partners/v1/clients/{id}
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "operationId": "getclients",
  "tags": [
    "Customers"
  ],
  "security": [
    {
      "partnerToken": [
        "clients:read"
      ]
    }
  ],
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/clientsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
PATCH · Operation details

Declared responses: 200, default

Full operation contract
{
  "operationId": "updateclients",
  "tags": [
    "Customers"
  ],
  "security": [
    {
      "partnerToken": [
        "clients:update"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    },
    {
      "in": "header",
      "name": "If-Match",
      "required": true,
      "schema": {
        "type": "string",
        "pattern": "^\"[1-9][0-9]*\"$"
      },
      "description": "ETag from last GET. Stale updates return 409."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/clientsUpdate"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/clientsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
GETPOST/api/partners/v1/service
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "operationId": "listservice",
  "tags": [
    "Repair orders"
  ],
  "security": [
    {
      "partnerToken": [
        "service:read"
      ]
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "maxLength": 128
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Records ordered by ID",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/serviceRecord"
                }
              },
              "pagination": {
                "type": "object",
                "properties": {
                  "next": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "limit": {
                    "type": "integer"
                  }
                },
                "required": []
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
POST · Operation details

Declared responses: 201, default

Full operation contract
{
  "operationId": "createservice",
  "tags": [
    "Repair orders"
  ],
  "security": [
    {
      "partnerToken": [
        "service:create"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/serviceCreate"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/serviceRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
GETPATCH/api/partners/v1/service/{id}
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "operationId": "getservice",
  "tags": [
    "Repair orders"
  ],
  "security": [
    {
      "partnerToken": [
        "service:read"
      ]
    }
  ],
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/serviceRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
PATCH · Operation details

Declared responses: 200, default

Full operation contract
{
  "operationId": "updateservice",
  "tags": [
    "Repair orders"
  ],
  "security": [
    {
      "partnerToken": [
        "service:update"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    },
    {
      "in": "header",
      "name": "If-Match",
      "required": true,
      "schema": {
        "type": "string",
        "pattern": "^\"[1-9][0-9]*\"$"
      },
      "description": "ETag from last GET. Stale updates return 409."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/serviceUpdate"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/serviceRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
GETPOST/api/partners/v1/parts
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "operationId": "listparts",
  "tags": [
    "Parts catalogue"
  ],
  "security": [
    {
      "partnerToken": [
        "parts:read"
      ]
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "maxLength": 128
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Records ordered by ID",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/partsRecord"
                }
              },
              "pagination": {
                "type": "object",
                "properties": {
                  "next": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "limit": {
                    "type": "integer"
                  }
                },
                "required": []
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
POST · Operation details

Declared responses: 201, default

Full operation contract
{
  "operationId": "createparts",
  "tags": [
    "Parts catalogue"
  ],
  "security": [
    {
      "partnerToken": [
        "parts:create"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/partsCreate"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/partsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
GETPATCH/api/partners/v1/parts/{id}
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "operationId": "getparts",
  "tags": [
    "Parts catalogue"
  ],
  "security": [
    {
      "partnerToken": [
        "parts:read"
      ]
    }
  ],
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/partsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
PATCH · Operation details

Declared responses: 200, default

Full operation contract
{
  "operationId": "updateparts",
  "tags": [
    "Parts catalogue"
  ],
  "security": [
    {
      "partnerToken": [
        "parts:update"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    },
    {
      "in": "header",
      "name": "If-Match",
      "required": true,
      "schema": {
        "type": "string",
        "pattern": "^\"[1-9][0-9]*\"$"
      },
      "description": "ETag from last GET. Stale updates return 409."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/partsUpdate"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/partsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
GETPOST/api/partners/v1/appointments
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "operationId": "listappointments",
  "tags": [
    "Sales appointments"
  ],
  "security": [
    {
      "partnerToken": [
        "appointments:read"
      ]
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "maxLength": 128
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Records ordered by ID",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/appointmentsRecord"
                }
              },
              "pagination": {
                "type": "object",
                "properties": {
                  "next": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "limit": {
                    "type": "integer"
                  }
                },
                "required": []
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
POST · Operation details

Declared responses: 201, default

Full operation contract
{
  "operationId": "createappointments",
  "tags": [
    "Sales appointments"
  ],
  "security": [
    {
      "partnerToken": [
        "appointments:create"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/appointmentsCreate"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/appointmentsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
GETPATCH/api/partners/v1/appointments/{id}
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "operationId": "getappointments",
  "tags": [
    "Sales appointments"
  ],
  "security": [
    {
      "partnerToken": [
        "appointments:read"
      ]
    }
  ],
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/appointmentsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
PATCH · Operation details

Declared responses: 200, default

Full operation contract
{
  "operationId": "updateappointments",
  "tags": [
    "Sales appointments"
  ],
  "security": [
    {
      "partnerToken": [
        "appointments:update"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    },
    {
      "in": "header",
      "name": "If-Match",
      "required": true,
      "schema": {
        "type": "string",
        "pattern": "^\"[1-9][0-9]*\"$"
      },
      "description": "ETag from last GET. Stale updates return 409."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/appointmentsUpdate"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/appointmentsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
POST/api/partners/applications
POST · Operation details

Exact allowed Origin and Turnstile action partner_application required. Submission grants no system access.

Declared responses: 201, default

Full operation contract
{
  "operationId": "submitPartnerApplication",
  "description": "Exact allowed Origin and Turnstile action partner_application required. Submission grants no system access.",
  "security": [],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "company": {
              "type": "string",
              "maxLength": 160
            },
            "contact_name": {
              "type": "string",
              "maxLength": 160
            },
            "email": {
              "type": "string",
              "format": "email",
              "maxLength": 254
            },
            "website": {
              "type": "string",
              "format": "uri",
              "maxLength": 500
            },
            "purpose": {
              "type": "string",
              "maxLength": 4000
            },
            "requested_scopes": {
              "type": "array",
              "minItems": 1,
              "uniqueItems": true,
              "items": {
                "type": "string",
                "enum": [
                  "inventory:read",
                  "inventory:create",
                  "inventory:update",
                  "leads:read",
                  "leads:create",
                  "leads:update",
                  "clients:read",
                  "clients:create",
                  "clients:update",
                  "service:read",
                  "service:create",
                  "service:update",
                  "parts:read",
                  "parts:create",
                  "parts:update",
                  "appointments:read",
                  "appointments:create",
                  "appointments:update",
                  "invoices:read",
                  "invoices:create",
                  "invoices:draft-update",
                  "payments:links",
                  "payments:read",
                  "payments:charge",
                  "payments:refund",
                  "events:subscribe",
                  "exports:create"
                ]
              }
            },
            "data_use": {
              "type": "string",
              "maxLength": 4000
            },
            "retention_days": {
              "type": "integer",
              "minimum": 0,
              "maximum": 3650
            },
            "turnstile": {
              "type": "string",
              "maxLength": 4096
            },
            "company_url": {
              "type": "string",
              "maxLength": 0
            },
            "details": {
              "type": "object",
              "properties": {
                "country": {
                  "type": "string",
                  "maxLength": 3000
                },
                "role": {
                  "type": "string",
                  "maxLength": 3000
                },
                "support": {
                  "type": "string",
                  "maxLength": 3000
                },
                "security": {
                  "type": "string",
                  "maxLength": 3000
                },
                "owners": {
                  "type": "string",
                  "maxLength": 3000
                },
                "app": {
                  "type": "string",
                  "maxLength": 3000
                },
                "model": {
                  "type": "string",
                  "maxLength": 3000
                },
                "execution": {
                  "type": "string",
                  "maxLength": 3000
                },
                "locations": {
                  "type": "string",
                  "maxLength": 3000
                },
                "demo": {
                  "type": "string",
                  "maxLength": 3000
                },
                "storage": {
                  "type": "string",
                  "maxLength": 3000
                },
                "retention": {
                  "type": "string",
                  "maxLength": 3000
                },
                "ai": {
                  "type": "string",
                  "maxLength": 3000
                },
                "incident": {
                  "type": "string",
                  "maxLength": 3000
                },
                "payments": {
                  "type": "string",
                  "maxLength": 3000
                },
                "paymentDetails": {
                  "type": "string",
                  "maxLength": 3000
                },
                "commercial": {
                  "type": "string",
                  "maxLength": 3000
                }
              },
              "required": [],
              "additionalProperties": false
            }
          },
          "required": [
            "company",
            "contact_name",
            "email",
            "website",
            "purpose",
            "requested_scopes",
            "data_use",
            "retention_days",
            "turnstile"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Stored application; manual screening pending",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "applicationId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "status": {
                    "const": "submitted"
                  }
                },
                "required": []
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
POST/api/partners/oauth/token
POST · Operation details

Code with S256 PKCE or rotating refresh token. Confidential clients authenticate. Client credentials/password grants unavailable.

Declared responses: 200, 400, 401, 503

Full operation contract
{
  "operationId": "exchangePartnerToken",
  "description": "Code with S256 PKCE or rotating refresh token. Confidential clients authenticate. Client credentials/password grants unavailable.",
  "security": [],
  "requestBody": {
    "required": true,
    "content": {
      "application/x-www-form-urlencoded": {
        "schema": {
          "type": "object",
          "properties": {
            "grant_type": {
              "enum": [
                "authorization_code",
                "refresh_token"
              ]
            },
            "client_id": {
              "type": "string",
              "format": "uuid"
            },
            "client_secret": {
              "type": "string",
              "writeOnly": true
            },
            "code": {
              "type": "string"
            },
            "code_verifier": {
              "type": "string",
              "minLength": 43,
              "maxLength": 128
            },
            "redirect_uri": {
              "type": "string",
              "format": "uri"
            },
            "refresh_token": {
              "type": "string",
              "writeOnly": true
            },
            "scope": {
              "type": "string"
            }
          },
          "required": [
            "grant_type"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Short-lived access token and rotated refresh token; store securely.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "access_token": {
                "type": "string"
              },
              "refresh_token": {
                "type": "string"
              },
              "expires_in": {
                "type": "integer"
              },
              "token_type": {
                "const": "Bearer"
              },
              "scope": {
                "type": "string"
              }
            },
            "required": []
          }
        }
      }
    },
    "400": {
      "description": "OAuth error"
    },
    "401": {
      "description": "Client authentication failed"
    },
    "503": {
      "description": "Partner access unavailable"
    }
  }
}
POST/api/partners/v1/payments/links
POST · Operation details

Reviewed processor and verified merchant connection required. USD is the only current currency. Stable intent; unknown outcomes cannot be resubmitted as new payments. Refund approval applies to one exact amount for 15 minutes. Sandbox adapter acceptance remains pending.

Declared responses: 201, 202, default

Full operation contract
{
  "operationId": "requestPaymentlinks",
  "description": "Reviewed processor and verified merchant connection required. USD is the only current currency. Stable intent; unknown outcomes cannot be resubmitted as new payments. Refund approval applies to one exact amount for 15 minutes. Sandbox adapter acceptance remains pending.",
  "security": [
    {
      "partnerToken": [
        "payments:links"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "invoiceId": {
              "type": "string",
              "maxLength": 128
            },
            "processorId": {
              "type": "string",
              "maxLength": 64
            },
            "amountMinor": {
              "type": "integer",
              "minimum": 1,
              "maximum": 99999999
            },
            "currency": {
              "const": "usd"
            }
          },
          "required": [
            "invoiceId",
            "processorId",
            "amountMinor",
            "currency"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Reserved intent and current state; does not itself prove funds settled.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Payment"
              }
            },
            "required": []
          }
        }
      }
    },
    "202": {
      "description": "Exact refund needs dealership administrator approval; resubmit identical key after approval.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Payment"
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
POST/api/partners/v1/payments/charges
POST · Operation details

Reviewed processor and verified merchant connection required. USD is the only current currency. Stable intent; unknown outcomes cannot be resubmitted as new payments. Refund approval applies to one exact amount for 15 minutes. Sandbox adapter acceptance remains pending.

Declared responses: 201, 202, default

Full operation contract
{
  "operationId": "requestPaymentcharges",
  "description": "Reviewed processor and verified merchant connection required. USD is the only current currency. Stable intent; unknown outcomes cannot be resubmitted as new payments. Refund approval applies to one exact amount for 15 minutes. Sandbox adapter acceptance remains pending.",
  "security": [
    {
      "partnerToken": [
        "payments:charge"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "invoiceId": {
              "type": "string",
              "maxLength": 128
            },
            "processorId": {
              "type": "string",
              "maxLength": 64
            },
            "amountMinor": {
              "type": "integer",
              "minimum": 1,
              "maximum": 99999999
            },
            "currency": {
              "const": "usd"
            },
            "savedMethodId": {
              "type": "string",
              "format": "uuid"
            }
          },
          "required": [
            "invoiceId",
            "processorId",
            "amountMinor",
            "currency",
            "savedMethodId"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Reserved intent and current state; does not itself prove funds settled.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Payment"
              }
            },
            "required": []
          }
        }
      }
    },
    "202": {
      "description": "Exact refund needs dealership administrator approval; resubmit identical key after approval.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Payment"
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
POST/api/partners/v1/payments/refunds
POST · Operation details

Reviewed processor and verified merchant connection required. USD is the only current currency. Stable intent; unknown outcomes cannot be resubmitted as new payments. Refund approval applies to one exact amount for 15 minutes. Sandbox adapter acceptance remains pending.

Declared responses: 201, 202, default

Full operation contract
{
  "operationId": "requestPaymentrefunds",
  "description": "Reviewed processor and verified merchant connection required. USD is the only current currency. Stable intent; unknown outcomes cannot be resubmitted as new payments. Refund approval applies to one exact amount for 15 minutes. Sandbox adapter acceptance remains pending.",
  "security": [
    {
      "partnerToken": [
        "payments:refund"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "invoiceId": {
              "type": "string",
              "maxLength": 128
            },
            "processorId": {
              "type": "string",
              "maxLength": 64
            },
            "amountMinor": {
              "type": "integer",
              "minimum": 1,
              "maximum": 99999999
            },
            "currency": {
              "const": "usd"
            },
            "parentId": {
              "type": "string",
              "format": "uuid"
            }
          },
          "required": [
            "invoiceId",
            "processorId",
            "amountMinor",
            "currency",
            "parentId"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Reserved intent and current state; does not itself prove funds settled.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Payment"
              }
            },
            "required": []
          }
        }
      }
    },
    "202": {
      "description": "Exact refund needs dealership administrator approval; resubmit identical key after approval.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Payment"
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
GET/api/partners/v1/payments/{id}
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "operationId": "readPayment",
  "security": [
    {
      "partnerToken": [
        "payments:read"
      ]
    }
  ],
  "responses": {
    "200": {
      "description": "Payment belonging to this installation and dealership.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Payment"
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
GETPOST/api/partners/events/subscriptions
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "operationId": "listSubscriptions",
  "security": [
    {
      "partnerToken": [
        "events:subscribe"
      ]
    }
  ],
  "responses": {
    "200": {
      "description": "Current installation subscriptions; operational controls still being completed.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "resources": {
                      "type": "array",
                      "items": {
                        "enum": [
                          "inventory",
                          "leads",
                          "clients",
                          "service",
                          "parts",
                          "appointments"
                        ]
                      }
                    },
                    "endpoint": {
                      "type": "string",
                      "format": "uri"
                    },
                    "status": {
                      "enum": [
                        "active",
                        "disabled"
                      ]
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": []
                },
                "maxItems": 100
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
POST · Operation details

Reviewed webhook origin, events:subscribe and each resource:read required. Only future events are sent. Secret shown once; keep it server-side. Event envelopes contain references only; fetch records through authorized API.

Declared responses: 201, default

Full operation contract
{
  "operationId": "createSubscription",
  "description": "Reviewed webhook origin, events:subscribe and each resource:read required. Only future events are sent. Secret shown once; keep it server-side. Event envelopes contain references only; fetch records through authorized API.",
  "security": [
    {
      "partnerToken": [
        "events:subscribe"
      ]
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "endpoint": {
              "type": "string",
              "format": "uri"
            },
            "resources": {
              "type": "array",
              "minItems": 1,
              "uniqueItems": true,
              "items": {
                "enum": [
                  "inventory",
                  "leads",
                  "clients",
                  "service",
                  "parts",
                  "appointments"
                ]
              }
            }
          },
          "required": [
            "endpoint",
            "resources"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Subscription signing secret shown once",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "status": {
                    "const": "active"
                  },
                  "signingSecret": {
                    "type": "string"
                  }
                },
                "required": []
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}