[{"data":1,"prerenderedAt":774},["ShallowReactive",2],{"docs:\u002Fdocs\u002Fsuscripciones-y-acceso":3,"docs-surround:\u002Fdocs\u002Fsuscripciones-y-acceso":751,"docs-navigation":759},{"id":4,"title":5,"body":6,"description":743,"extension":744,"meta":745,"navigation":746,"path":747,"seo":748,"stem":749,"__hash__":750},"docs\u002Fdocs\u002F3.suscripciones-y-acceso.md","Suscripciones y estados de acceso",{"type":7,"value":8,"toc":735},"minimark",[9,21,26,82,123,127,227,236,240,246,353,381,385,388,423,518,540,544,547,596,607,611,724,731],[10,11,12,13,20],"p",{},"Paygumi te dice qué hacer con tu usuario en un solo campo: ",[14,15,16],"strong",{},[17,18,19],"code",{},"access_status",". Viene en cada webhook de suscripción y de pago, y lo puedes consultar en cualquier momento. Con él no tienes que reimplementar reglas de mora, días de gracia ni cancelaciones.",[22,23,25],"h2",{"id":24},"estado-de-acceso","Estado de acceso",[27,28,29,43],"table",{},[30,31,32],"thead",{},[33,34,35,40],"tr",{},[36,37,38],"th",{},[17,39,19],{},[36,41,42],{},"Qué hacer",[44,45,46,62,72],"tbody",{},[33,47,48,55],{},[49,50,51],"td",{},[52,53],"status-badge",{"status":54},"GRANTED",[49,56,57,58,61],{},"Dar acceso. Dura hasta ",[17,59,60],{},"access_until"," (fin del periodo, de la prueba o de la gracia).",[33,63,64,69],{},[49,65,66],{},[52,67],{"status":68},"RESTRICTED",[49,70,71],{},"El pago está vencido y ya pasaron los días de gracia: limita el acceso y pide actualizar la tarjeta.",[33,73,74,79],{},[49,75,76],{},[52,77],{"status":78},"REVOKED",[49,80,81],{},"Sin acceso.",[10,83,84,85,87,88,91,92,95,96,99,100,99,103,99,106,99,109,99,112,99,115,118,119,122],{},"En la API el valor va en mayúsculas (",[17,86,54],{},"); en el cuerpo de los webhooks, en minúsculas (",[17,89,90],{},"granted","). El motivo viene en ",[17,93,94],{},"access_reason",": ",[17,97,98],{},"ACTIVE",", ",[17,101,102],{},"TRIAL",[17,104,105],{},"GRACE_PERIOD",[17,107,108],{},"PAYMENT_FAILED",[17,110,111],{},"UNPAID",[17,113,114],{},"PAUSED",[17,116,117],{},"CANCELED"," o ",[17,120,121],{},"NO_SUBSCRIPTION",".",[22,124,126],{"id":125},"estados-de-la-suscripción","Estados de la suscripción",[27,128,129,142],{},[30,130,131],{},[33,132,133,136,139],{},[36,134,135],{},"Estado",[36,137,138],{},"Acceso",[36,140,141],{},"Significado",[44,143,144,158,171,188,201,214],{},[33,145,146,151,155],{},[49,147,148],{},[52,149],{"status":150},"TRIALING",[49,152,153],{},[17,154,54],{},[49,156,157],{},"Periodo de prueba, sin cobro.",[33,159,160,164,168],{},[49,161,162],{},[52,163],{"status":98},[49,165,166],{},[17,167,54],{},[49,169,170],{},"El periodo actual está pagado (o su primer cobro está en curso).",[33,172,173,178,185],{},[49,174,175],{},[52,176],{"status":177},"PAST_DUE",[49,179,180,182,183],{},[17,181,54],{}," durante la gracia, luego ",[17,184,68],{},[49,186,187],{},"Un cobro fue rechazado y hay reintentos pendientes.",[33,189,190,194,198],{},[49,191,192],{},[52,193],{"status":111},[49,195,196],{},[17,197,78],{},[49,199,200],{},"Se agotaron los reintentos. La suscripción sigue viva: si el cliente paga, se reactiva.",[33,202,203,207,211],{},[49,204,205],{},[52,206],{"status":114},[49,208,209],{},[17,210,78],{},[49,212,213],{},"Pausada; no se generan cobros.",[33,215,216,220,224],{},[49,217,218],{},[52,219],{"status":117},[49,221,222],{},[17,223,78],{},[49,225,226],{},"Terminada.",[10,228,229,230,233,234,122],{},"Una cancelación programada (",[17,231,232],{},"cancel_at_period_end: true",") mantiene el acceso hasta el fin del periodo y luego pasa a ",[17,235,117],{},[22,237,239],{"id":238},"pagos-rechazados-y-reintentos","Pagos rechazados y reintentos",[10,241,242,243,245],{},"Cuando el cobro de un periodo es rechazado, la suscripción pasa a ",[17,244,177],{}," y Paygumi lo reintenta según la política de tu cuenta (configurable en el panel). La política por defecto:",[27,247,248,262],{},[30,249,250],{},[33,251,252,255,258,260],{},[36,253,254],{},"Paso",[36,256,257],{},"Cuándo",[36,259,135],{},[36,261,138],{},[44,263,264,285,301,318,334],{},[33,265,266,269,272,280],{},[49,267,268],{},"Intento 1",[49,270,271],{},"Día de cobro",[49,273,274,276,277,279],{},[17,275,98],{}," → ",[17,278,177],{}," si falla",[49,281,282,284],{},[17,283,54],{}," (gracia)",[33,286,287,290,293,297],{},[49,288,289],{},"Reintento 1",[49,291,292],{},"+1 día",[49,294,295],{},[17,296,177],{},[49,298,299,284],{},[17,300,54],{},[33,302,303,306,309,313],{},[49,304,305],{},"Reintento 2",[49,307,308],{},"+3 días",[49,310,311],{},[17,312,177],{},[49,314,315,317],{},[17,316,68],{}," (gracia de 3 días vencida)",[33,319,320,323,326,330],{},[49,321,322],{},"Reintento 3",[49,324,325],{},"+5 días",[49,327,328],{},[17,329,177],{},[49,331,332],{},[17,333,68],{},[33,335,336,339,342,349],{},[49,337,338],{},"Agotado",[49,340,341],{},"—",[49,343,344,118,346,348],{},[17,345,111],{},[17,347,117],{},", según tu política",[49,350,351],{},[17,352,78],{},[10,354,355,356,359,360,99,363,366,367,375,376,380],{},"Cada paso te llega por webhook (",[17,357,358],{},"payment.declined"," trae ",[17,361,362],{},"next_retry_at",[17,364,365],{},"payment.uncollectible"," cuando se agotan). Si el cliente actualiza su tarjeta con una ",[368,369,371,372],"a",{"href":370},"\u002Fdocs\u002Fsesiones-de-checkout#modo-setup","sesión ",[17,373,374],{},"setup"," o desde el ",[368,377,379],{"href":378},"\u002Fdocs\u002Fportal-del-cliente","portal",", se reintenta de inmediato.",[22,382,384],{"id":383},"consultar-el-acceso","Consultar el acceso",[10,386,387],{},"El webhook es la fuente principal, pero puedes consultar el acceso calculado en este momento (por ejemplo, en el login de tu usuario o para reconciliar):",[389,390,395],"pre",{"className":391,"code":392,"language":393,"meta":394,"style":394},"language-bash shiki shiki-themes github-light github-dark","curl https:\u002F\u002Fapi.paygumi.com\u002Fv1\u002Fcustomers\u002Fby-external-id\u002Fuser_42\u002Faccess \\\n  -H \"Authorization: Bearer pgm_test_...\"\n","bash","",[17,396,397,414],{"__ignoreMap":394},[398,399,402,406,410],"span",{"class":400,"line":401},"line",1,[398,403,405],{"class":404},"sScJk","curl",[398,407,409],{"class":408},"sZZnC"," https:\u002F\u002Fapi.paygumi.com\u002Fv1\u002Fcustomers\u002Fby-external-id\u002Fuser_42\u002Faccess",[398,411,413],{"class":412},"sj4cs"," \\\n",[398,415,417,420],{"class":400,"line":416},2,[398,418,419],{"class":412},"  -H",[398,421,422],{"class":408}," \"Authorization: Bearer pgm_test_...\"\n",[389,424,428],{"className":425,"code":426,"language":427,"meta":394,"style":394},"language-json shiki shiki-themes github-light github-dark","{\n  \"access_status\": \"GRANTED\",\n  \"access_until\": \"2026-12-01T05:00:00Z\",\n  \"subscription_id\": \"sub_01JB86R800ABCDEFGHJKMNPQRS\",\n  \"subscription_status\": \"ACTIVE\",\n  \"last_payment_status\": \"PAID\",\n  \"reason\": \"ACTIVE\"\n}\n","json",[17,429,430,436,449,462,475,488,501,512],{"__ignoreMap":394},[398,431,432],{"class":400,"line":401},[398,433,435],{"class":434},"sVt8B","{\n",[398,437,438,441,443,446],{"class":400,"line":416},[398,439,440],{"class":412},"  \"access_status\"",[398,442,95],{"class":434},[398,444,445],{"class":408},"\"GRANTED\"",[398,447,448],{"class":434},",\n",[398,450,452,455,457,460],{"class":400,"line":451},3,[398,453,454],{"class":412},"  \"access_until\"",[398,456,95],{"class":434},[398,458,459],{"class":408},"\"2026-12-01T05:00:00Z\"",[398,461,448],{"class":434},[398,463,465,468,470,473],{"class":400,"line":464},4,[398,466,467],{"class":412},"  \"subscription_id\"",[398,469,95],{"class":434},[398,471,472],{"class":408},"\"sub_01JB86R800ABCDEFGHJKMNPQRS\"",[398,474,448],{"class":434},[398,476,478,481,483,486],{"class":400,"line":477},5,[398,479,480],{"class":412},"  \"subscription_status\"",[398,482,95],{"class":434},[398,484,485],{"class":408},"\"ACTIVE\"",[398,487,448],{"class":434},[398,489,491,494,496,499],{"class":400,"line":490},6,[398,492,493],{"class":412},"  \"last_payment_status\"",[398,495,95],{"class":434},[398,497,498],{"class":408},"\"PAID\"",[398,500,448],{"class":434},[398,502,504,507,509],{"class":400,"line":503},7,[398,505,506],{"class":412},"  \"reason\"",[398,508,95],{"class":434},[398,510,511],{"class":408},"\"ACTIVE\"\n",[398,513,515],{"class":400,"line":514},8,[398,516,517],{"class":434},"}\n",[10,519,520,521,524,525,528,529,532,533,536,537,122],{},"Si el usuario no existe o no tiene suscripciones, la respuesta es ",[17,522,523],{},"200"," con ",[17,526,527],{},"access_status: REVOKED"," y ",[17,530,531],{},"reason: NO_SUBSCRIPTION",". Con varias suscripciones se devuelve la de mejor acceso; filtra con ",[17,534,535],{},"?plan_id="," si necesitas un plan concreto. Por id de suscripción: ",[17,538,539],{},"GET \u002Fv1\u002Fsubscriptions\u002F{id}\u002Faccess",[22,541,543],{"id":542},"crear-una-suscripción-sin-página-de-pago","Crear una suscripción sin página de pago",[10,545,546],{},"Si el cliente ya registró su tarjeta, suscríbelo directamente:",[389,548,550],{"className":391,"code":549,"language":393,"meta":394,"style":394},"curl https:\u002F\u002Fapi.paygumi.com\u002Fv1\u002Fsubscriptions \\\n  -H \"Authorization: Bearer pgm_test_...\" \\\n  -H \"Idempotency-Key: 9b1f6c2e-4d3a-4c8e-8f0a-2e7d5b1c9a33\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{ \"customer_id\": \"cus_01JB86R800ABCDEFGHJKMNPQRS\", \"plan_id\": \"pln_01JB86R800ABCDEFGHJKMNPQRS\" }'\n",[17,551,552,561,570,579,588],{"__ignoreMap":394},[398,553,554,556,559],{"class":400,"line":401},[398,555,405],{"class":404},[398,557,558],{"class":408}," https:\u002F\u002Fapi.paygumi.com\u002Fv1\u002Fsubscriptions",[398,560,413],{"class":412},[398,562,563,565,568],{"class":400,"line":416},[398,564,419],{"class":412},[398,566,567],{"class":408}," \"Authorization: Bearer pgm_test_...\"",[398,569,413],{"class":412},[398,571,572,574,577],{"class":400,"line":451},[398,573,419],{"class":412},[398,575,576],{"class":408}," \"Idempotency-Key: 9b1f6c2e-4d3a-4c8e-8f0a-2e7d5b1c9a33\"",[398,578,413],{"class":412},[398,580,581,583,586],{"class":400,"line":464},[398,582,419],{"class":412},[398,584,585],{"class":408}," \"Content-Type: application\u002Fjson\"",[398,587,413],{"class":412},[398,589,590,593],{"class":400,"line":477},[398,591,592],{"class":412},"  -d",[398,594,595],{"class":408}," '{ \"customer_id\": \"cus_01JB86R800ABCDEFGHJKMNPQRS\", \"plan_id\": \"pln_01JB86R800ABCDEFGHJKMNPQRS\" }'\n",[10,597,598,599,603,604,122],{},"Si no tiene tarjeta, usa una ",[368,600,602],{"href":601},"\u002Fdocs\u002Fsesiones-de-checkout","sesión de checkout"," en modo ",[17,605,606],{},"subscription",[22,608,610],{"id":609},"cancelar-pausar-y-cambiar-de-plan","Cancelar, pausar y cambiar de plan",[27,612,613,626],{},[30,614,615],{},[33,616,617,620,623],{},[36,618,619],{},"Acción",[36,621,622],{},"Ruta",[36,624,625],{},"Notas",[44,627,628,647,669,691,704],{},[33,629,630,633,638],{},[49,631,632],{},"Cancelar ya",[49,634,635],{},[17,636,637],{},"POST \u002Fv1\u002Fsubscriptions\u002F{id}\u002Fcancel",[49,639,640,641,643,644,646],{},"Pasa a ",[17,642,117],{}," con acceso ",[17,645,78],{}," y anula el cobro abierto.",[33,648,649,652,659],{},[49,650,651],{},"Cancelar al final del periodo",[49,653,654,524,656],{},[17,655,637],{},[17,657,658],{},"{\"at_period_end\": true}",[49,660,661,662,665,666,122],{},"Mantiene el acceso hasta ",[17,663,664],{},"current_period_end",". Se deshace con ",[17,667,668],{},"POST \u002Fv1\u002Fsubscriptions\u002F{id}\u002Fundo-cancel",[33,670,671,674,679],{},[49,672,673],{},"Pausar",[49,675,676],{},[17,677,678],{},"POST \u002Fv1\u002Fsubscriptions\u002F{id}\u002Fpause",[49,680,681,682,118,684,686,687,690],{},"Solo ",[17,683,98],{},[17,685,177],{},". Sin cobros ni acceso. ",[17,688,689],{},"resume_at"," opcional programa la reanudación.",[33,692,693,696,701],{},[49,694,695],{},"Reanudar",[49,697,698],{},[17,699,700],{},"POST \u002Fv1\u002Fsubscriptions\u002F{id}\u002Fresume",[49,702,703],{},"Empieza un periodo desde hoy con cobro inmediato.",[33,705,706,709,714],{},[49,707,708],{},"Cambiar de plan",[49,710,711],{},[17,712,713],{},"POST \u002Fv1\u002Fsubscriptions\u002F{id}\u002Fchange-plan",[49,715,716,719,720,723],{},[17,717,718],{},"timing: NEXT_PERIOD"," (por defecto) al cierre del periodo, o ",[17,721,722],{},"IMMEDIATE"," con un cobro del plan nuevo completo (sin prorrateo).",[10,725,726,727,122],{},"Todos los detalles en la ",[368,728,730],{"href":729},"\u002Fdocs\u002Fapi\u002Fsuscripciones","referencia de suscripciones",[732,733,734],"style",{},"html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}",{"title":394,"searchDepth":451,"depth":451,"links":736},[737,738,739,740,741,742],{"id":24,"depth":416,"text":25},{"id":125,"depth":416,"text":126},{"id":238,"depth":416,"text":239},{"id":383,"depth":416,"text":384},{"id":542,"depth":416,"text":543},{"id":609,"depth":416,"text":610},"Estados de una suscripción, el campo access_status con el que decides si tu usuario tiene acceso, reintentos de pagos rechazados y cómo cancelar, pausar o cambiar de plan.","md",{},true,"\u002Fdocs\u002Fsuscripciones-y-acceso",{"title":5,"description":743},"docs\u002F3.suscripciones-y-acceso","gJ7JSb4a5w0g0WWjJ1ATKEC2l0JBjnmvOYKgei9K3U8",[752,755],{"title":753,"path":601,"stem":754,"children":-1},"Crear una sesión de checkout","docs\u002F2.sesiones-de-checkout",{"title":756,"path":757,"stem":758,"children":-1},"Webhooks","\u002Fdocs\u002Fwebhooks","docs\u002F4.webhooks",[760,763,766,767,768,769,771],{"title":761,"path":762},"Introducción","\u002Fdocs",{"title":764,"path":765},"Primeros pasos","\u002Fdocs\u002Fprimeros-pasos",{"title":753,"path":601},{"title":5,"path":747},{"title":756,"path":757},{"title":770,"path":378},"Portal del cliente",{"title":772,"path":773},"Idempotencia y errores","\u002Fdocs\u002Fidempotencia-y-errores",1794279320101]