{
  "openapi": "3.1.0",
  "info": {
    "title": "Cancel consumer offer",
    "version": "1.0.0"
  },
  "paths": {
    "/consumerOffers/{consumerOfferId}/cancellation": {
      "post": {
        "tags": [
          "Consumer Offers"
        ],
        "summary": "Cancel Consumer Offer",
        "description": "Cancel a consumer offer and all underlying entitlements.",
        "operationId": "Cancel_consumer_offer_consumerOffers__consumerOfferId__cancellation_post",
        "parameters": [
          {
            "name": "consumerOfferId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Identifier of the consumer offer",
              "title": "Consumerofferid"
            },
            "description": "Identifier of the consumer offer"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConsumerOfferCancellation"
              },
              "examples": {
                "End of term cancellation": {
                  "value": {
                    "cancellationType": "END_OF_TERM",
                    "reasonCode": "SUBSCRIPTION_CANCELLED",
                    "reasonDescription": "Customer has cancelled the subscription"
                  }
                },
                "Immediate cancellation": {
                  "value": {
                    "cancellationType": "IMMEDIATE",
                    "reasonCode": "ACCOUNT_TERMINATED",
                    "reasonDescription": "Customer has closed their account with the reseller"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsumerOfferReadForCancel"
                },
                "examples": {
                  "Accepted": {
                    "value": {
                      "consumerOffer": {
                        "consumerOfferId": "338d31e1-a289-40dd-beff-ab41c1fc5f51",
                        "offerId": "7560fca0-d8a9-4124-a172-924debec874e",
                        "consumer": {
                          "consumerIdentifier": "RFBNZ2MU3Y35OA5GNNNGETK6JTEVRYVB"
                        },
                        "status": "FULLY_ACTIVE",
                        "subStatus": "PENDING_CANCELS",
                        "timeline": {
                          "plannedCancellationTs": "2025-12-21T00:00:00Z"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "examples": {
                  "Bad Request": {
                    "value": {
                      "message": "Bad Request",
                      "statusCode": 400
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid credentials (no response body returned)"
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "examples": {
                  "Not found": {
                    "value": {
                      "message": "Not found",
                      "statusCode": 404
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "examples": {
                  "Conflict": {
                    "value": {
                      "message": "Conflict",
                      "statusCode": 409
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "examples": {
                  "Internal server error": {
                    "value": {
                      "message": "Internal server error",
                      "statusCode": 500
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ActionSchedule": {
        "type": "string",
        "enum": [
          "END_OF_TERM",
          "IMMEDIATE"
        ],
        "title": "ActionSchedule",
        "description": "Scheduling type for an action."
      },
      "CancellationReasonCode": {
        "type": "string",
        "enum": [
          "NOT_RENEWED",
          "CHANGED_SERVICE",
          "SUBSCRIPTION_CANCELLED",
          "ADDON_CANCELLED",
          "EXPIRED",
          "ACCOUNT_TERMINATED",
          "SUSPEND_TERMINATED",
          "ERROR",
          "FRAUD",
          "IMMEDIATE_CANCELLATION",
          "CUSTOMER_CANCELLED",
          "OTHER"
        ],
        "title": "CancellationReasonCode",
        "description": "Reason code for the cancellation."
      },
      "CommunicationInformation": {
        "properties": {
          "emailAddress": {
            "type": "string",
            "title": "Emailaddress",
            "description": "An email address that can be used to contact the consumer."
          },
          "msisdn": {
            "type": "string",
            "title": "Msisdn",
            "description": "A mobile phone number that can be used to contact the consumer, with international prefix"
          }
        },
        "type": "object",
        "title": "CommunicationInformation",
        "description": "Communication channel with the consumer."
      },
      "Consumer": {
        "properties": {
          "consumerIdentifier": {
            "type": "string",
            "maxLength": 400,
            "title": "Consumeridentifier",
            "description": "Consumer identifier"
          },
          "billingIdentifier": {
            "type": "string",
            "title": "Billingidentifier",
            "description": "Billing identifier"
          },
          "communicationInformation": {
            "$ref": "#/components/schemas/CommunicationInformation",
            "title": "Communicationinformation",
            "description": "Communication channel with the consumer. May be used to send reminders or important information."
          }
        },
        "type": "object",
        "required": [
          "consumerIdentifier"
        ],
        "title": "Consumer",
        "description": "Consumer."
      },
      "ConsumerOfferCancellation": {
        "properties": {
          "cancellationType": {
            "$ref": "#/components/schemas/ActionSchedule",
            "description": "Cancellation type\n\n* `END_OF_TERM`: consumer retains access to the service until the end of the current term\n* `IMMEDIATE`: consumer immediately loses access to the service\n",
            "default": "IMMEDIATE"
          },
          "reasonCode": {
            "$ref": "#/components/schemas/CancellationReasonCode",
            "title": "Reasoncode",
            "description": "Cancellation reason\n\n* `NOT_RENEWED`: Customer has not renewed their entitlement\n* `CHANGED_SERVICE`: Customer has changed content provider/service\n* `SUBSCRIPTION_CANCELLED`: Customer has cancelled the subscription\n* `ADDON_CANCELLED`: Customer has cancelled the add-on\n* `EXPIRED`: Scheduled cancellation by Bango (based on dateExpiry set during entitlement creation by the reseller)\n* `OTHER`: Cancelled for any other reason\n* `ACCOUNT_TERMINATED`: Consumer has closed their account with the reseller\n* `SUSPEND_TERMINATED`: Suspended entitlement has been cancelled based on suspension terms\n* `ERROR`: Consumer offer/subscription created by mistake\n* `FRAUD`: Fraud detected or suspected\n* `IMMEDIATE_CANCELLATION`: Cancellation for fraud or suspected fraud reasons\n"
          },
          "reasonDescription": {
            "type": "string",
            "maxLength": 500,
            "title": "Reasondescription",
            "description": "Human readable description of the reason for cancelling"
          }
        },
        "type": "object",
        "title": "ConsumerOfferCancellation",
        "description": "Consumer offer cancellation action."
      },
      "ConsumerOfferCancellationDetail": {
        "properties": {
          "consumerOfferId": {
            "type": "string",
            "format": "uuid",
            "title": "Consumerofferid",
            "description": "A globally unique and immutable identifier of the Consumer Offer",
            "examples": [
              "338d31e1-a289-40dd-beff-ab41c1fc5f51"
            ]
          },
          "offerId": {
            "type": "string",
            "format": "uuid",
            "title": "Offer ID",
            "description": "A globally unique and immutable identifier of the offer the consumer has subcribed to.",
            "examples": [
              "7560fca0-d8a9-4124-a172-924debec874e"
            ]
          },
          "consumer": {
            "$ref": "#/components/schemas/Consumer",
            "description": "Consumer data."
          },
          "status": {
            "$ref": "#/components/schemas/ConsumerOfferStatus",
            "description": "Consumer offer status:\n\n* `REQUESTED`: creation of the consumer offer was requested\n* `PARTIALLY_CREATED`: some entitlement were created, but others failed\n* `FULLY_CREATED`: all entitlements have been created\n* `CREATES_FAILED`: all entitlements failed to be created\n* `FULLY_ACTIVE`: all entitlements are active\n* `FULLY_TERMINATED`: all entitlements have been terminated\n* `PARTIALLY_TERMINATED`: some entitlement terminated succesfully, some terminations failed\n"
          },
          "subStatus": {
            "$ref": "#/components/schemas/ConsumerOfferSubStatus",
            "title": "Substatus",
            "description": "Consumer offer sub-status:\n\n* `PENDING_CREATES`: entitlement creation is pending\n* `PENDING_ACTIVATES`: entitlement activation is pending\n* `PENDING_TERMINATES`: entitlement termination is pending\n* `PENDING_CANCELS`: entitlement cancellation is pending\n"
          },
          "timeline": {
            "$ref": "#/components/schemas/ConsumerOfferCancellationTimeline",
            "description": "Timeline of changes made to the consumer offer"
          }
        },
        "type": "object",
        "required": [
          "consumerOfferId",
          "offerId",
          "consumer",
          "status",
          "timeline"
        ],
        "title": "ConsumerOfferCancellationDetail",
        "description": "Consumer offer detail."
      },
      "ConsumerOfferCancellationTimeline": {
        "properties": {
          "plannedCancellationTs": {
            "type": "string",
            "format": "date-time",
            "title": "Plannedcancellationts",
            "description": "Scheduled date and time for cancel"
          }
        },
        "type": "object",
        "required": [
          "plannedCancellationTs"
        ],
        "title": "ConsumerOfferCancellationTimeline",
        "description": "Consumer Offer timeline."
      },
      "ConsumerOfferReadForCancel": {
        "properties": {
          "consumerOffer": {
            "$ref": "#/components/schemas/ConsumerOfferCancellationDetail",
            "description": "Consumer offer detail"
          }
        },
        "type": "object",
        "required": [
          "consumerOffer"
        ],
        "title": "ConsumerOfferReadForCancel",
        "description": "Consumer offer in a get response."
      },
      "ConsumerOfferStatus": {
        "type": "string",
        "enum": [
          "REQUESTED",
          "PARTIALLY_CREATED",
          "FULLY_CREATED",
          "CREATES_FAILED",
          "FULLY_ACTIVE",
          "FULLY_TERMINATED",
          "PARTIALLY_TERMINATED"
        ],
        "title": "ConsumerOfferStatus",
        "description": "Consumer offer status."
      },
      "ConsumerOfferSubStatus": {
        "type": "string",
        "enum": [
          "PENDING_CREATES",
          "PENDING_ACTIVATES",
          "PENDING_TERMINATES",
          "PENDING_CANCELS"
        ],
        "title": "ConsumerOfferSubStatus",
        "description": "Consumer Offer sub-status."
      },
      "ErrorResponse": {
        "properties": {
          "statusCode": {
            "type": "integer",
            "title": "Statuscode",
            "description": "HTTP Status Code"
          },
          "message": {
            "type": "string",
            "title": "Message",
            "description": "Description of the error"
          }
        },
        "type": "object",
        "title": "ErrorResponse",
        "description": "Error response for Consumer Offer API."
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          },
          "input": {
            "title": "Input"
          },
          "ctx": {
            "type": "object",
            "title": "Context"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      }
    }
  }
}